( 



UNISYS U 6000 Series 

System V 

Programmer's 
Reference Manual 

Volume 2 

Copyright © 1988 Unisys Corporation. 
( Unisys is a trademark of Unisys Corporation. 



March 1988 

Printed in U S America 
Priced Item UP-13712.3 



This document is intended for software releases based on AT&T Release 3 of UNIX 
System V or a subsequent release of the System unless otherwise indicated. 

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any 
product and related material disclosed herein are only furnished pursuant and subject to 
the terms and conditions of a duly executed Program Product License or Agreement to 
purchase or lease equipment. The only warranties made by Unisys, if any, with respect 
to the products described in this document are set forth in such License or Agreement. 
Unisys cannot accept any financial or other responsibility that may be the result of your 
use of the information in this document or software material, including direct, indirect, 
special or consequential damages. 

You should be very careful to ensure that the use of this information and/or software 
material complies with the laws, rules, and regulations of the jurisdictions with respect to 
which it is used. 

The information contained herein is subject to change without notice. Revisions may be 
issued to advise of such changes and/or additions. 

ACT, Micro-Term, and MIME are trademarks of Micro-Term. 

Ann Arbor is a trademark of Ann Arbor Terminals. 

Beehive and Superbee are registered trademarks of Beehive International. 

Concept is a trademark of Human Designed Systems. 

DEC, PDP, VAX, and VT100 are trademarks of Digital Equipment Corp. 

Diablo is a registered trademark of Xerox Corp. 

DOCUMENTER'S WORKBENCH is a trademark of AT&T. Teletype and WE are registered 
trademarks of AT&T. UNIX is a registered trademark of AT&T in the USA and other 
countries. 

HP and Hewlett-Packard 45 are registered trademarks of Hewlett-Packard, Inc. 
LSI ADM is a trademark of Lear Siegler. 

TEKTRONIX, TEKTRONIX 4010, and TEKTRONIX 4014 are registered trademarks of 
Tektronix, Inc. 

Teleray and Teleray 1061 are trademarks of Research. 
TeleVideo is a registered trademark of TeleVideo Systems. 

Texas Instruments, TI735, TI725, and TI745 are registered trademarks of Texas 
Instruments, Inc. 

Versatec and Versatec D1200A are registered trademarks of Versatec Corp. 

Portions of this material are copyrighted <D by 
AT&T Technologies 
and are reprinted with their permission. 

This documentation is based in part on the fourth Berkeley Software Distribution, under license from the Regents of the 
University of California We acknowledge the following Individuals and Institutions for their role in its development: 

Computer Science Division 
Department of Electrical Engineering and Computer Science 
University of California 
Berkeley, California 94720 



6000/50 

Customization Package 



This customization package contains changes to your 
Programmer's Reference Manual, Volume 2, which reflect the AT&T 
System V Release 3.1 and the value-added features of the Unisys 
System V Operating System. Please add these pages to your base 
manual to produce a fully customized Programmer's Reference 
Manual. 



To fully customize your Programmer's Reference Manual, 
Volume 1, replace the existing generic manual cover with the 
new customized manual cover. 



Customization 



1 



Customization Package 



Customization Directions 



The table below indicates the name of the document and 
directions for making your manual current. The document found 
in your customization package may be used to replace an already 
existing document of the same name, or it may be added as a 
new document to the manual. You may also be directed to 
remove an existing document from the current manual. For the 
location of specific documents, please refer to the Table of 
Contents. 



New Customization Document 


Customization Directions 


Table of Contents 


replace old with new 


intro(3) 


replace old with new 


dbm(3B) 


add new 


ndbm(3B) 


add new 


ctime(3C) 


replace old with new 


ctype(3C) 


replace old with new 


dial(3C) 


replace old with new 


fpgetround(3C) 


replace old with new 


crypt (3X) 


replace old with new 


curses (3X) 


replace old with new 


libdev(3X) 


add new 


ocurse(3X) 


add new 


otermcap(3X) 


add new 


sputl(3X) 


add new 
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(The following are contained in three volumes.) 



Table of Contents 



1 . Commands 

intro(1) introduction to commands and applications programs 

admin(1) create and administer SCCS files 

adb(1) absolute debugger 

ar(1) archive and library maintainor for portable archives 

as(1) common assembler 

astgen(1) .... generate/modify ASSIST menus and command forms 

bs(1) a compiler/interpreter for modest sized programs 

buildgrp(1) build software distributions 

cb(1) C program beautifier 

cc(1) C compiler 

cdc(1) change the delta commentary of an SCCS delta 

cflow(1) generate C flowgraph 

comb(1) combine SCCS deltas 

cpp(1) the C language preprocessor 

cprs(1) compress a common object file 

ctags(1) create a tags file 

ctrace(1) C program debugger 

cxref(1) generate C program cross-reference 

delta(1) make a delta (change) to an SCCS file 

dis(1) object code disassembler 

dump(1) dump selected parts of an object file 

efl(1) extended FORTRAN language 

fsplit(1) split f77, ratfor, or efl files 

gencc(1M) create a front-end to the cc command 

get(1) get a version of an SCCS file 

i286emul(1) emulate 80286 

includes(1) determine C language preprocessor include files 

inline(1) substitute inline code in asm file 

infocmp(IM) compare or print out terminfo descriptions 

install(IM) install commands 
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ld(1) link editor for common object files 

lex(1) generate programs for simple lexical tasks 

lint(1) a C program checker 

list(1) produce C source listing from a common object file 

lorder(1) find ordering relation for an object library 

m4(1) macro processor 

make(1) maintain, update, and regenerate groups of programs 

mcs(1) manipulate the object file comment section 

mkshlib(1) create a shared library 

mkstr(1B) create error message file from C source 

nm(1) print name list of common object file 

prof(1) display profile data 

prs(1) print an SCCS file 

ratfor(1) rational FORTRAN dialect 

regcmp(1) regular expression compile 

rmdel(1) remove a delta from an SCCS file 

sact(1) print current SCCS file editing activity 

sccsdiff(1) compare two versions of an SCCS file 

sdb(1) symbolic debugger 

size(1) print section sizes in bytes of common object files 

sno(1) SNOBOL interpreter 

strip(1) strip symbol & line no. info, from a common object file 

sym(1) display symbols 

tic(1M) terminfo compiler 

tsort(1) topological sort 

unget(1) undo a previous get of an SCCS file 

val(1) validate SCCS file 

vc(1) version control 

what(1) identify SCCS files 

xstr(1) extract and share strings in C program 

yacc(1) yet another compiler-compiler 

2. System Calls 

intro(2) introduction to system calls and error numbers 

access(2) determine accessibility of a file 

acct(2) enable or disable process accounting 

alarm (2) set a process alarm clock 

brk(2) change data segment space allocation 

chdir(2) change working directory 

chmod(2) change mode of file 

chown(2) change owner and group of a file 
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chroot(2) change root directory 

close(2) close a file descriptor 

creat(2) create a new file or rewrite an existing one 

dup(2) duplicate an open file descriptor 

exec (2) execute a file 

exit(2) terminate process 

fcntl(2) file control 

fork(2) create a new process 

getdents(2) read directory entries and put in a file 

getmsg(2) get next message off a stream 

getpid(2) get process, process group, and parent process IDs 

gettimeofday, settimeofday(2) get/set date and time 

getuid(2) .. get real user, effective user, real grp., effective grp. IDs 

ioctl(2) control device 

kill (2) send a signal to a process or a group of processes 

lddrv(2) access loadable drivers 

link(2) link to a file 

lseek(2) move read/write file pointer 

mkdir(2) make a directory 

mknod(2) make a directory, or a special or ordinary file 

mount(2) mount a file system 

msgctl(2) message control operations 

msgget(2) get message queue 

msgop(2) message operations 

nice(2) change priority of a process 

notify, unnotify, evwait, evnowait(2) manage notifications 

open(2) open for reading or writing 

pause(2) suspend process until signal 

pipe(2) create an interprocess channel 

plock(2) lock process, text, or data in memory 

poll (2) STREAMS input/output multiplexing 

profil(2) execution time profile 

ptrace(2) process trace 

putmsg(2) send a message on a stream 

read (2) read from file 

rmdir(2) remove a directory 

semctl(2) semaphore control operations 

semget(2) get set of semaphores 

semop(2) semaphore operations 

setpgrp(2) set process group ID 

setuid(2) set user and group IDs 
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shmctl(2) shared memory control operations 

shmget(2) get shared memory segment identifier 

shmop(2) shared memory operations 

signal (2) specify what to do upon receipt of a signal 

sigset(2) signal management 

stat (2) get file status 

staffs (2) get file system information 

stime(2) set time 

sync(2) update super block 

sysfs(2) get file system type information 

sysi86(2) machine specific functions 

time (2) get time 

times (2) get process and child process times 

uadmin(2) administrative control 

ulimit(2) get and set user limits 

umask(2) set and get file creation mask 

umount(2) unmount a file system 

uname(2) get name of current UNIX system 

unlink(2) remove directory entry 

ustat(2) get file system statistics 

utime(2) set file access and modification times 

wait(2) wait for child process to stop or terminate 

write(2) write on a file 

3. Subroutines 

intro(3) introduction to functions and libraries 

dbm(3B) data base subroutines 

ndbm(3B) data base subroutines 

a64l(3C) .... convert between long integer and base-64 ASCII string 

abort(3C) generate an IOT fault 

abs(3C) return integer absolute value 

bsearch(3C) binary search a sorted table 

clock(3C) report CPU time used 

crypt(3C) generate hashing encryption 

ctermid(3S) generate file name for terminal 

ctime, localtime, gmtime, asctime, tzset(3C) 

convert date and time to string 

ctype: isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, 

ispucnt, isprint, isgraph, iscntrl, isascii(3C) classify characters 

cuserid(3S) get character login name of the user 

dial(3C) establish an out-going terminal line connection 
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drand48(3C) ... generate uniformly distributed pseudo-random no.s 



dup2(3C) duplicate an open file descriptor 

ecvt(3C) convert floating-point number to string 

end(3C) last locations in program 

f close (3S) close or flush a stream 

ferror(3S) stream status inquiries 

fopen(3S) open a stream 

fpget round (3C) IEEE floating point environment control 

fread(3S) binary input/output 

frexp(3C) manipulate parts of floating-point numbers 

fseek(3S) reposition a file pointer in a stream 

ftw(3C) walk a file tree 

getc(3S) get character or word from a stream 

getcwd(3C) get path-name of current working directory 

getenv(3C) return value for environment name 

getgrent(3C) get group file entry 

getlogin(3C) get login name 

getopt(3C) get option letter from argument vector 

getpass(3C) read a password 

getpw(3C) get name from UID 

getpwent(3C) get password file entry 

gets(3S) get a string from a stream 

getut(3C) access utmp file entry 

hsearch(3C) manage hash search tables 

isnan(3C) test for floating point NaN (Not-A-Number) 

l3tol(3C) convert between 3-byte integers and long integers 

lockf(3C) record locking on files 

lsearch(3C) linear search and update 

malloc(3C) main memory allocator 

memory(3C) memory operations 

mktemp(3C) make a unique file name 

monitor(3C) prepare execution profile 

nlist(3C) get entries from name list 

perror(3C) system error messages 

popen(3S) initiate pipe to/from a process 

printf(3S) print formatted output 

putc(3S) put character or word on a stream 

putenv(3C) change or add value to environment 

putpwent(3C) write password file entry 

puts(3S) put a string on a stream 

qsort(3C) quicker sort 



UP-13712.3 



Contents 5 



rand(3C) simple random-number generator 

scant (3S) convert formatted input 

setbuf (3S) assign buffering to a stream 

setjmp(3C) non-local goto 

sleep(3C) suspend execution for interval 

ssignal(3C) software signals 

stdio(3S) standard buffered input/output package 

stdipc(3C) standard interprocess communication package 

string (3C) string operations 

strtod(3C) convert string to double-precision number 

strtol(3C) convert string to integer 

swab(3C) swap bytes 

system (3S) issue a shell command 

tmpfile(3S) create a temporary file 

tmpnam(3S) create a name for a temporary file 

tsearch(3C) manage binary search trees 

ttyname(3C) find name of a terminal 

ttyslot(3C) find the slot in the utmp file of the current user 

ungetc(3S) push character back into input stream 

vprintf (3S) print formatted output of a varargs argument list 

bessel(3M) Bessel functions 

erf (3M) error function and complementary error function 

exp(3M) exponential, logarithm, power, square root functions 

floor(3M) floor, ceiling, remainder, absolute value functions 

gamma (3M) log gamma function 

hypot(3M) Euclidean distance function 

matherr(3M) error-handling function 

sinh(3M) hyperbolic functions 

trig(3M) trigonometric functions 

t_accept(3N) accept a connect request 

t_alloc(3N) allocate a library structure 

t_bind(3N) bind an address to a transport endpoint 

t_close(3N) close a transport endpoint 

t_connect(3N) .. establish a connection with another transport user 

t_error(3N) produce error message 

t_free(3N) free a library structure 

t_getinfo(3N) get protocol-specific service information 

t_getstate(3N) get the current state 

t_listen(3N) listen for a connect request 

t_look(3N) look at the current event on a transport endpoint 

t_open(3N) establish a transport endpoint 
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t_optmgmt(3N) manage options for a transport endpoint 

t_rcv(3N) .... receive data or expedited data sent over a connection 
t_rcvconnect(3N) . receive the confirmation from a connect request 

t_rcvdis(3N) retrieve information from disconnect 

t_rcvrel(3N) ... acknowledge receipt of an orderly release indication 

t_rcvudata(3N) receive a data unit 

t_rcvuderr(3N) receive a unit data error indication 

t_snd(3N) send data or expedited data over a connection 

t_snddis(3N) send user-initiated disconnect request 

t_sndrel(3N) initiate an orderly release 

t_sndudata(3N) send a data unit 

t_sync(3N) synchronize transport library 

t_unbind(3N) disable a transport endpoint 

assert(3X) verify program assertion 

crypt(3X) password and file encryption functions 

curses(3X) terminal screen handling and optimization package 

directory(3X) directory operations 

ldahread(3X) ... read archive header of a member of an archive file 

ldclose(3X) close a common object file 

ldfhread(3X) read the file header of a common object file 

ldgetname(3X) retrieve sym. name for common obj. file sym. table 
ldlread(3X) manipulate line no. entries of common obj. file function 
ldlseek(3X) .... seek to line no. entries of sect of a common obj. file 

ldohseek(3X) seek to optional file header of common obj file 

ldopen(3X) open a common object file for reading 

ldrseek(3X) seek to relocation entries of sect, of a common obj. file 
ldshread(3X) read indexed/named sect, header of common obj. file 

ldsseek(3X) seek to indexed/named sect, of common obj. file 

ldtbindex(3X) ... compute index of sym. table entry of com. obj. file 

ldtbread(3X) read indexed sym. table entry of common obj. file 

ldtbseek(3X) seek to the symbol table of a common object file 

libdev(3X) manipulate Volume Home Blocks (VHB) 

logname(3X) return login name of user 

malloc(3X) fast main memory allocator 

ocurse(3X) optimized screen functions 

otermcap(3X) terminal independent operations 

plot(3X) graphics interface subroutines 

regcmp(3X) compile and execute regular expression 

sputl, sgetl(3X) 

access long integer data in a machine independent fashion 

abort(3F) terminate Fortran program 
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abs(3F) Fortran absolute value 

acos(3F) Fortran arccosine intrinsic function 

aimag(3F) Fortran imaginary part of complex argument 

aint(3F) Fortran integer part intrinsic function 

asin(3F) Fortran arcsine intrinsic function 

atan(3F) Fortran arctangent intrinsic function 

atan2(3F) Fortran arctangent intrinsic function 

bool(3F) Fortran Bitwise Boolean functions 

conjg(3F) Fortran complex conjugate intrinsic function 

cos(3F) Fortran cosine intrinsic function 

cosn(3F) Fortran hyperbolic cosine intrinsic function 

dim(3F) positive difference intrinsic functions 

dprod(3F) double precision product intrinsic function 

exp(3F) Fortran exponential intrinsic function 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, 

fpsetsticky(3C) IEEE floating point environment control 

ftype(3F) explicit Fortran type conversion 

getarg(3F) return Fortran command-line argument 

getenv(3F) return Fortran environment variable 

iargc(3F) return the number of command line arguments 

index(3F) return location of Fortran substring 

len(3F) return length of Fortran string 

log(3F) Fortran natural logarithm intrinsic function 

log10(3F) Fortran common logarithm intrinsic function 

max(3F) Fortran maximum-value functions 

mclock(3F) return Fortran time accounting 

mil(3F) Fortran Military Standard functions 

min(3F) Fortran minimum-value functions 

mod(3F) Fortran remaindering intrinsic functions 

rand(3F) random number generator 

round (3F) Fortran nearest integer functions 

sign(3F) Fortran transfer-of-sign intrinsic function 

signal (3F) specify Fortran action on receipt of a system signal 

sin(3F) Fortran sine intrinsic function 

sinh(3F) Fortran hyperbolic sine intrinsic function 

sqrt(3F) Fortran square root intrinsic function 

strcmp(3F) string comparison intrinsic functions 

system (3F) issue a shell command from Fortran 

tan(3F) Fortran tangent intrinsic function 

tanh(3F) Fortran hyperbolic tangent intrinsic function 
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4. File Formats 



intro(4) introduction to file formats 

a.out(4) common assembler and link editor output 

acct(4) per-process accounting file format 

ar(4) common archive file format 

checklist (4) list of file systems processed by fsck and ncheck 

core(4) format of core image file 

cpio(4) format of cpio archive 

cprofile(4) setting up a C shell environment at login time 

dir(4) format of directories 

dirent(4) file system independent directory entry 

errfile(4) error-log file format 

filehdr(4) file header for common object files 

fs(4) format of system volume 

fspec(4) format specification in text files 

f stab (4) file-system-table 

gettydefs(4) speed and terminal settings used by getty 

gps(4) graphical primitive string, format of graphical files 

group(4) group file 

inittab(4) script for the init process 

inode(4) format of an i-node 

isort(4) international sort 

issue(4) issue identification file 

ldfcn(4) common object file access routines 

limits (4) file header for implementation-specific constants 

linenum(4) line number entries in a common object file 

master(4) master device information table 

mnttab(4) mounted file system table 

otermcap(4) terminal capability data base 

passwd(4) password file 

plot(4) graphics interface 

profile(4) setting up an environment at login time 

prsetup(4) international printer spooler 

reloc(4) relocation information for a common object file 

rfmaster(4) Remote File Sharing name server master file 

sccsfile(4) format of SCCS file 

scnhdr(4) section header for a common object file 

scr_dump(4) format of curses screen image file 

syms(4) common object file symbol table format 

system (4) system description file 

term (4) format of compiled term file 
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terminfo(4) terminal capability data base 

timezone(4) set default system time zone 

ttytype(4) list of terminal types by terminal number 

tz(4) time zone file 

unistd(4) file header for symbolic constants 

utmp(4) utmp and wtmp entry formats 

5. Miscellaneous Facilities 

intro(5) introduction to miscellany 

ascii(5) map of ASCII character set 

environ (5) user environment 

eqnchar(5) special character definitions for eqn and neqn 

fcntl(5) file control options 

math (5) math functions and constants 

man (5) macros for formatting entries in this manual 

me (5) macros for formatting papers 

mm (5) macro package for formatting documents 

mptx(5) the macro package for formatting a permuted index 

ms(5) text formatting macros 

mvt(5) 

a troff macro package for typesetting view graphs and slides 

prof (5) profile within a function 

regexp(5) regular expression compile and match routines 

stat(5) data returned by stat system call 

term (5) conventional names for terminals 

types (5) primitive system data types 

values (5) machine-dependent values 

varargs(5) handle variable argument list 
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NAME 

intro - introduction to functions and libraries 
DESCRIPTION 

This section describes functions found in various libraries other 
than those functions that directly invoke System V system 
primitives, which are described in Section 2 of this volume. 
Certain major collections are identified by a letter after the 
section number: 

(3C) These functions, together with those of Section 2 and 
those marked (3S), constitute the Standard C Library 
//6c, which is automatically loaded by the C compiler, 
cc(1). The link editor /d(1) searches this library under 
the -Ic option. A "shared library" version of //6c can be 
searched using the -lc_s option, resulting in smaller 
a.outs. Declarations for some of these functions may 
be obtained from #include files indicated on the 
appropriate pages. 

(3S) These functions constitute the "standard I/O package" 
[see stdio (3S)]. These functions are in the library libc, 
already mentioned. Declarations for these functions 
may be obtained from the #include file < stdio.h > . 

(3M) These functions constitute the Math Library, //6m. They 
are not automatically loaded by the C compiler, cc(1); 
however, the link editor searches this library under the 
-Im option. Declarations for these functions may be 
obtained from the #include file <math.h>. Several 
generally useful mathematical constants are also 
defined there [see math {5)]. 

(3N) This contains sets of functions constituting the Network 
Services library. These sets provide protocol indepen- 
dent interfaces to networking services based on the ser- 
vice definitions of the OSI (Open Systems Interconnec- 
tion) reference model. Application developers access 
the function sets that provide services at a particular 
level. 

This library contains the functions of the TRANSPORT 
INTERFACE (TI) - provide the services of the OSI Tran- 
sport Layer. These services provide reliable end-to-end 
data transmission using the services of an underlying 
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network. Applications written using the TI functions are 
independent of the underlying protocols. Declarations 
for these functions may be obtained from the #include 
file <tiuser.h>. The link editor /c/(1) searches this 
library under the -lnsl_s option. 

(3B) These functions are part of the System V BSD Berkeley 
networking package. To use these functions you must 
have the network protocols on your system. 

(3X) Various specialized libraries. The files in which these 
libraries are found are given on the appropriate pages. 

DEFINITIONS 
character 

Any bit pattern able to fit into a byte on the machine, 
null character 

A character with value 0, represented in the C language 
as '\0\ 

character array 

A sequence of characters. 

null-terminated character array 

A sequence of characters, the last of which is the null 
character. 

string 

A designation for a null-terminated character array. 
null string 

A character array containing only the null character. 
NULL pointer 

The value that is obtained by casting 0 into a pointer. The 
C language guarantees that this value will not match that 
of any legitimate pointer, so many functions that return 
pointers return it to indicate an error. 

NULL 

Defined as 0 in <stdio.h>; the user can include an 
appropriate definition if not using < stdio.h > . 

Netbuf 

In the Network Services library, netbuf is a structure used in 
various Transport Interface (TI) functions to send and receive 
data and information. It contains the following members: 
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unsigned int max 1 en; 
unsigned int len; 
char *buf ; 

Buf points to a user input and/or output buffer. Len generally 
specifies the number of bytes contained in the buffer. If the 
structure is used for both input and output, the function will 
replace the user value of len on return. 

Maxlen generally has significance only when buf is used to 
receive output from the TI function. In this case, it specifies 
the physical size of the buffer, the maximum value of len that 
can be set by the function. If maxlen is not large enough to 
hold the returned information, an TBUFOVFLW error will gen- 
erally result. However, certain functions may return part of 
the data and not generate an error. 

FILES 

/lib 

/lib/libc.a 
/lib/libcs.a 
/lib/libm.a 
/shlib/libc_s 
/shlib/libnsl_s (3N) 
/usr/lib/libnsl_s.a (3N) 

SEE ALSO 

ar(1), cc(1), ld(1), lint(1), nm(1), intro(2), stdio(3S), math(5). 

DIAGNOSTICS 

Functions in the C and Math Libraries (3C and 3M) may return 
the conventional values 0 or ± HUGE (the largest-magnitude 
single- precision floating-point numbers; HUGE is defined in 
the <math.h> header file) when the function is undefined for 
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the given arguments or when the value is not representable. 
In these cases, the external variable errno [see intro{2)] is set 
to the value EDOM or ERANGE. 

WARNING 

Many of the functions in the libraries call and/or refer to other 
functions and external variables described in this section and 
in Section 2 {System Calls). If a program inadvertently defines 
a function or external variable with the same name, the 
presumed library version of the function or external variable 
may not be loaded. The lint (1) program checker reports name 
conflicts of this kind as "multiple declarations" of the names in 
question. Definitions for Sections 2, 3C, and 3S are checked 
automatically. Other definitions can be included by using the 
-I option. (For example, -\m includes definitions for Section 
3M, the Math Library.) Use of lint is highly recommended. 
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NAME 

dbminit, fetch, store, delete, firstkey, nextkey - data base sub- 
routines 

SYNOPSIS 

#include <dbm.h> 

typedef struct { 

char *dptr; 

int dsize; 
} datum; 

dbminit(file) 
char *file; 

datum fetch(key) 
datum key; 

store(key, content) 
datum key, content; 

delete(key) 
datum key; 

datum firstkey() 

datum nextkey(key) 
datum key; 

DESCRIPTION 

These functions maintain key/content pairs in a data base. 
The functions handle very large (a billion blocks) databases 
and access a keyed item in one or two file system accesses. 
The functions are obtained with the loader option -Idbm. 

Keys and contents are described by the datum typedef. A 
datum specifies a string of dsize bytes pointed to by dptr. 
Arbitrary binary data, as well as normal ASCII strings, are 
allowed. The data base is stored in two files. One file is a 
directory containing a bit map and has .dir as its suffix. The 
second file contains all data and has .pag as its suffix. 

Before a database can be accessed, it must be opened by 
dbminit. At the time of this call, the files file. dir and file. pag 
must exist. An empty database is created by creating zero- 
length .dir and .pag files. 

Once open, the data stored under a key is accessed by fetch 
and data is placed under a key by store. A key (and its 
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associated contents) is deleted by delete. A linear pass 
through all keys in a database may be made, in (apparently) 
random order, by use of firstkey and nextkey. Firstkey returns 
the first key in the database. With any key nextkey returns the 
next key in the database. This code traverses the data base: 

for (key = firstkey( ); key.dptr != NULL; 
key = nextkey (key ) ) 

DIAGNOSTICS 

All functions that return an int indicate errors with negative 
values. A zero return indicates OK. Routines that return a 
datum indicate errors with a null (0) dptr. 

BUGS 

The .pag file contains holes so that its apparent size is about 
four times its actual content. Other UNIX systems may create 
real file blocks for these holes when touched. These files can- 
not be copied by normal means (cp, cat, tp, tar, ar) without 
filling in the holes. 

Dptr pointers returned by these subroutines point into static 
storage that is changed by subsequent calls. 

The sum of the sizes of a key/content pair must not exceed 
the internal block size (currently 1024 bytes). Moreover all 
key/content pairs that hash together must fit on a single 
block. Store returns an error in the event that a disk block fills 
with inseparable data. 

Delete does not physically reclaim file space, although it does 
make it available for reuse. 

The order of keys presented by firstkey and nextkey depends 
on a hashing function, not on anything interesting. 
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NAME 

dbm_open, dbm_close, dbm_fetch, dbm_store, dbm_delete, 
dbm_firstkey, dbm_nextkey, dbm_error, dbm_clearerr - data 
base subroutines 

SYNOPSIS 

#include <ndbm.h> 

typedef struct { 

char *dptr; 

int dsize; 
} datum; 

DBM *dbm_open(file, flags, mode) 

char *file; 

int flags, mode; 

void dbm close(db) 
DBM *db; 

datum dbm_fetch(db, key) 
DBM *db; 
datum key; 

int dbm_store(db, key, content, flags) 
DBM *db; 

datum key, content; 
int flags; 

int dbm_delete(db, key) 
DBM *db; 
datum key; 

datum dbmfirstkey(db) 
DBM *db; 

datum dbm nextkey(db) 
DBM *db; 

int dbm error(db) 
DBM *db; 

int dbm clearerr(db) 
DBM *db; 

DESCRIPTION 

These functions maintain key/content pairs in a data base. 
The functions handle very large databases (a billion blocks) 
and access a keyed item in one or two file system accesses. 
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This package replaces, and is incompatible with, the earlier 
dbm (3B) library, which managed only a single database. 

Keys and contents are described by the datum typedef. A 
datum specifies a string of dsize bytes pointed to by dptr. 
Arbitrary binary data, as well as normal ASCII strings, are 
allowed. The data base is stored in two files. One file is a 
directory containing a bit map and has .dir as its suffix. The 
second file contains all data and has .pag as its suffix. 

Before a database can be accessed, it must be opened by 
dbm_open. This opens and/or creates the files We .dir and 
file. pag depending on the flags parameter [see open (2)]. 

Once open, the data stored under a key is accessed by 
dbmjetch and data is placed under a key by dbmjstore. The 
flags field can be either DBMINSERT or DBM_REPLACE. 
DBMJNSERT only inserts new entries into the database and 
does not change an existing entry with the same key. 
DBM_REPLACE replaces an existing entry if it has the same 
key. A key (and its associated contents) is deleted by 
dbm_delete. A linear pass through all keys in a database may 
be made, in an (apparently) random order, by use of 
dbmjirstkey and dbm_nextkey. Dbmjirstkey returns the first 
key in the database. Dbm_nextkey returns the next key in the 
database. This code traverses the database: 

for (key = dbm_f irstkey(db); key. dptr != NULL; 
key = dbm_nextkey(db) ) 

Dbmjerror returns non-zero when an error has occurred read- 
ing or writing the database. Dbm_clearerr resets the error 
condition on the named database. 

DIAGNOSTICS 

All functions that return an int indicate errors with negative 
values. A zero return indicates no error condition. Routines 
that return a datum indicate errors with a null (0) dptr. If 
dbmstore is called with a flags value of DBM INSERT, and 
finds an existing entry with the same key, it returns 1. 

WARNINGS 

The .pag file contains holes so that its apparent size is about 
four times its actual content. These files cannot be copied by 
normal means (cp, cat, tp, tar, ar) without filling in the holes. 
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Dptr pointers returned by these subroutines point into static 
storage that is changed by subsequent calls. 

The sum of the sizes of a key/content pair must not exceed 
the internal block size (currently 4096 bytes). Moreover all 
key/content pairs that hash together must fit in a single block. 
Dbmstore returns an error in the event that a disk block fills 
with inseparable data. 

Dbm_delete does not physically reclaim file space, although it 
does make it available for reuse. 

The order of keys presented by dbmjirstkey and 
dbmjiextkey depends on a hashing function, not on anything 
interesting. 

SEE ALSO 

dbm(3B). 

NOTE 

This function is for use with a version of the System V kernel 
that supports networking protocols. 
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NAME 

ctime, localtime, gmtime, asctime, tzset - convert date and 
time to string 

SYNOPSIS 

^include < sys/types.h > 
#include <time.h> 

char *ctime (clock) 
time_t *clock; 

struct tm *localtime (clock) 
time_t *clock; 

struct tm *gmtime (clock) 
time_t *clock; 

char *asctime (tm) 
struct tm *tm; 

extern long timezone; 

extern int daylight; 

extern char *tzname[2]; 

void tzset () 

DESCRIPTION 

Ctime converts a long integer, pointed to by clock, represent- 
ing the time in seconds since 00:00:00 GMT, January 1, 1970, 
and returns a pointer to a 26-character string in the following 
form. All the fields have constant width. 

Sun Sep 16 01:03:52 1985\n\0 

Localtime and gmtime return pointers to tm structures, 
described below. Localtime corrects for the time zone and 
possible Daylight Savings Time; gmtime converts directly to 
Greenwich Mean Time (GMT), which is the time the System V 
system uses. 

Asctime converts a tm structure to a 26-character string, as 
shown in the above example, and returns a pointer to the 
string. 

Declarations of all the functions and externals, and the tm 
structure, are in the <time.h> header file. The structure 
declaration is: 
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struct tm \ 

int tm_sec; /* seconds (0 - 59) */ 

int tm_min; /* minutes (0 - 59) */ 

int tm_hour; /* hours (0 - 23) */ 

int tm_mday; /* day of month (1 - 31) */ 

int tmjnon; /* month of year (0 - 11) */ 

int tm_year; /* year - 1900 */ 

int tm_wday; /* day of week (Sunday = 0) */ 

int tm_yday; /* day of year (0 - 365) */ 

int tm_isdst; 

i; 

Tmjsdst is non-zero if Daylight Savings Time is in effect. 

The external long variable timezone contains the difference, in 
seconds, between GMT and local standard time (in EST, 
timezone is 5*60*60); the external variable daylight is non-zero 
if and only if the standard U.S.A. Daylight Savings Time 
conversion should be applied. The program knows about the 
peculiarities of this conversion in 1974 and 1975; if necessary, 
a table for these years can be extended. 

If an environment variable named TZ is present, asctime uses 
the contents of the variable to override the default time zone. 
The value of TZ must be a three-letter time zone name, fol- 
lowed by a number representing the difference between local 
time and Greenwich Mean Time in hours, followed by an 
optional three-letter name for a daylight time zone. For exam- 
ple, the setting for New Jersey would be EST5EDT. The 
effects of setting TZ are thus to change the values of the 
external variables timezone and daylight; in addition, the time 
zone names contained in the external variable 

char *tzname[2] = [ "EST", "EDT" J; 
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are set from the environmentvariable TZ. The function tzset 
sets these external variables from TZ; tzset is called by asc- 
time and may also be called explicitly by the user. 

Note that in most installations, TZ is set by default when the 
user logs on, to a value in the local /etc/profile file [see pro- 
file (4)]. 

SEE ALSO 

time(2), getenv(3C), profile(4), environ(5). 

CAVEAT 

The return values point to static data whose content is 
overwritten by each call. 



UP-13712.3 



Page 3 



CTIME(3C) 



[This page left blank.] 



Page 4 



UP-13712.3 



CTYPE(3C) 



NAME 

ctype: isalpha, isupper, islower, isdigit, isxdigit, isalnum, 
isspace, ispunct, isprint, isgraph, iscntrl, isascii - classify char- 
acters 

SYNOPSIS 

#include < ctype. h> 

int isalpha (c) 
int c; 

DESCRIPTION 

These macros classify character-coded integer values by table 
lookup. Each is a predicate returning nonzero for true, zero 
for false. Isascii is defined on all integer values; the rest are 
defined only where isascii is true and on the single non-ASCII 
value EOF [-1; see stdio (3S)]. 

isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f]. 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, newline, vertical 



tab, or form-feed. 



ispunct 



c is a punctuation character (neither control nor 
alphanumeric). 



isprint 



c is a printing character, code 040 (space) 
through 0176 (tilde). 

c is a printing character, like isprint except false 
for space. 



isgraph 



iscntrl 



c is a delete character (0177) or an ordinary con- 
trol character (less than 040). 



isascii 



c is an ASCII character, code less than 0200. 



SEE ALSO 

stdio (3S), ascii(5). 
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DIAGNOSTICS 

If the argument to any of these macros is not in the domain of 
the function, the result is undefined. 
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NAME 

dial - establish an out-going terminal line connection 

SYNOPSIS 

#include <dial.h> 

int dial (call) 
CALL call; 

void undial (fd) 
int fd; 

DESCRIPTION 

Dial returns a file-descriptor for a terminal line open for 
read/write. The argument to dial is a CALL structure (defined 
in the <dial.h> header file). 

When finished with the terminal line, the calling program must 
invoke undial to release the semaphore that has been set dur- 
ing the allocation of the terminal device. 

The definition of CALL in the <dial.h> header file is: 
typedef struct { 



struct 


termio *attr; 


/* 


pointer to termio */ 






/* 


attribute struct */ 


int 


baud; 


/* 


transmission data rate */ 


int 


speed; 


/* 


21 2A modem: low=300, */ 






/* 


high=1200 */ 


char 


*1 ine; 


/* 


device name for out- */ 






/* 


going line */ 


char 


*telno; 


/* 


pointer to tel-no */ 






/* 


digits string */ 


int 


modem; 


/* 


specify modem control */ 






/* 


for direct 1 ines */ 


char 


*device; 


/* 


Will hold the name of the */ 






/* 


device used to make a */ 






/* 


connection */ 


int 


devjen; 


/* 


The length of the */ 






/* 


device used to make */ 






/* 


connection */ 



1 CALL; 

The call element speed is intended only for use with an out- 
going dialed call, in which case its value should be either 300 
or 1200 to identify the 113A modem, or the high- or low-speed 
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setting on the 21 2A modem. Note that the 113A modem or 
the low-speed setting of the 21 2A modem will transmit at any 
rate between 0 and 300 bits per second. However, the high- 
speed setting of the 21 2A modem transmits and receives at 
1200 bits per secound only. The CALL element baud is for the 
desired transmission baud rate. For example, one might set 
baud to 110 and speed to 300 (or 1200). However, if speed 
set to 1200 baud must be set to high (1200). 

If the desired terminal line is a direct line, a string pointer to its 
device-name should be placed in the line element in the CALL 
structure. Legal values for such terminal device names are 
kept in the L-devices file. In this case, the value of the baud 
element need not be specified as it will be determined from 
the L-devices file. 

The telno element is for a pointer to a character string 
representing the telephone number to be dialed. The termina- 
tion symbol will be supplied by the dial function, and should 
not be included in the telno string passed to dial in the CALL 
structure. 

The CALL element modem is used to specify modem control 
for direct lines. This element should be non-zero if modem 
control is required. The CALL element attr is a pointer to a 
termio structure, as defined in the <termio.h> header file. A 
NULL value for this pointer element may be passed to the dial 
function, but if such a structure is included, the elements 
specified in it will be set for the outgoing terminal line before 
the connection is established. This is often important for cer- 
tain attributes such as parity and baud- rate. 

The CALL element device is used to hold the device name 
(cul. .) that establishes the connection. 

The CALL element devjen is the length of the device name 
that is copied into the array device. 

FILES 

/usr/lib/uucp/L- devices 
/usr/spool/uucp/LCK. .tty-device 

SEE ALSO 

alarm (2), read (2), write (2). 

termio(7) in the Administrator's Reference Manual. 
uucp(lC) in the User's Reference Manual. 
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DIAGNOSTICS 

On failure, a negative value indicating the reason for the 
failure will be returned. Mnemonics for these negative indices 
as listed here are defined in the <dial.h> header file. 



INTRPT 


- 1 


/* 


interrupt occurred */ 


D_HUNG 


-2 


/* 


dialer hung (no return from write) */ 


NO_ANS 


-3 


/* 


no answer within 10 seconds */ 


ILL_BD 


-4 


/* 


illegal baud- rate */ 


A_PROB 


-5 


/* 


acu problem (open() failure) */ 


L_PROB 


-6 


/* 


line problem (open() failure) */ 


NO_Ldv 


-7 


/* 


can't open LDEVS file */ 


DV_NT_A 


-8 


/* 


requested device not available */ 


DV_NT_K 


-9 


/* 


requested device not known */ 


NO_BD_A 


-10 


/* 


no device available at requested baud */ 


NO_BD_K 


- 11 


/* 


no device known at requested baud */ 


DV_NT_E 


-12 


/* 


requested speed does not match */ 



WARNINGS 

The dial {3C) library function is not compatible with Basic Net- 
working Utilities on UNIX System V Release 2.0. 

Including the <dial.h> header file automatically includes the 
<termio.h> header file. 

The above routine uses <stdio.h>, which causes it to 
increase the size of programs, not otherwise using standard 
I/O, more than might be expected. 

BUGS 

An alarm (2) system call for 3600 seconds is made (and 
caught) within the dial module for the purpose of "touching" 
the LCK. . file and constitutes the device allocation semaphore 
for the terminal device. Otherwise, ut/cp(lC) may simply 
delete the LCK.. entry on its 90-minute clean-up rounds. The 
alarm may go off while the user program is in a read{2) or 
write (2) system call, causing an apparent error return. If the 
user program expects to be around for an hour or more, error 
returns from reads should be checked for (errno= =EINTR), 
and the read possibly reissued. 
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NAME 

fpgetround, fpsetround, fpgetmask, fpsetmask, fpgetsticky, 
fpsetsticky - IEEE floating point environment control 

SYNOPSIS 

#include <ieeefp.h> 

typedef enum { 

FP_RN = 0, /* round to nearest */ 

FP_RZ=0x10, /* round to zero (truncate) */ 
FP_RM = 0x20, /* round to minus */ 

FP_RP = 0x30, /* round to plus */ 
} fp_rnd; 

fp_rnd fpgetround 0; 

fp_rnd fpsetround (rnd_dir) 
fp_rnd rnd_dir; 



#define 


fp except 


int 






#define 


FP_X_INV 


0x80 


/* 


invalid operation */ 








/* 


exception */ 


#define 


FP_X_OFL 


0x40 


/* 


overflow */ 








/* 


exception */ 


#define 


FP_X_UFL 


0x20 


/* 


underflow */ 








/* 


exception */ 


#define 


FP_X_DZ 


0x10 


/* 


divide-by-zero */ 








/* 


exception */ 


#define 


FP_X_IMP 


0x08 


/* 


imprecise (loss */ 








/* 


of precision) */ 



fp_except fpgetmaskO; 

fp_except fpsetmask (mask); 
fp except mask; 

fp_except fpgetstickyO; 

fp_except fpsetsticky (sticky); 
fp_except sticky; 

DESCRIPTION 

These routines let the user change the behavior on occurrence 
of any of five floating point exceptions: divide-by-zero, over- 
flow, underflow, imprecise (inexact) result, and invalid opera- 
tion. The routines also change the rounding mode for floating 
point operations. When a floating point exception occurs, the 
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corresponding sticky bit is set (1), and if the mask bit is 
enabled (1), the trap takes place. The routines are valid only 
on systems that are equipped with floating point accelerator 
hardware; otherwise, floating point operations are compiled 
differently and handled in software. 

fpgetroundft returns the current rounding mode. 

fpsetroundf) sets the rounding mode and returns the previous 
rounding mode. 

fpgetmaskf) returns the current exception masks. 

fpsetmaskQ sets the exception masks and returns the previ- 
ous setting. 

fpgetstickyf) returns the current exception sticky flags. 

fpsetstickyf) sets (clears) the exception sticky flags and 
returns the previous setting. 

The environment for Convergent computers that combine the 
MC68020 CPU with the MC6888 1 or MC68882 floating point 
processor is: 

• Rounding mode set to nearest(FP_RN), 

• Divide-by-zero, 

• Floating point overflow, and 

• Invalid operation traps enabled. 

SEE ALSO 

isnan(3C). 

WARNINGS 

fpsetstickyf) modifies all sticky flags. fpsetmaskQ changes all 
mask bits. 

C requires truncation (round to zero) for floating point to 
integral conversions. The current rounding mode has no 
effect on these conversions. 

CAVEATS 

The utilities described in this manual page are applicable only 
for computers that are equipped with both the MC68020 
microprocessor for the CPU and the MC68881 or MC68882 
microprocessor for a hardware floating point accelerator. Pro- 
grams that invoke these utilities that are run on computers 
without the floating point hardware result in no operation and 
no returned error message for the particular function. 



Page 2 



UP-1 3712.3 



FPGETROUND (3C) 



One must clear the sticky bit to recover from the trap and to 
proceed. If the sticky bit is not cleared before the next trap 
occurs, a wrong exception type may be signaled. 

For the same reason, when calling fpsetmask() the user should 
make sure that the sticky bit corresponding to the exception 
being enabled is cleared. 
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NAME 

crypt - password and file encryption functions 

SYNOPSIS 

cc [flag ...] file ... -Icrypt [library ...] 

char *crypt (key, salt) 
char *key, *salt; 

void setkey (key) 
char *key; 

void encrypt (block, flag) 
char *block; 
int flag; 

char *des_crypt (key, salt) 
char *key, *salt; 

void des setkey (key) 
char *key; 

void des encrypt (block, flag) 
char *block; 
int flag; 

int run setkey (p, key) 
int p[2]; 
char *key; 

int run crypt (offset, buffer, count, p) 
long offset; 
char *buffer; 
unsigned int count; 
int p[2]; 

int crypt close(p) 
int p[2]; 

DESCRIPTION 

Des crypt is the password encryption function. It is based on 
a one way hashing encryption algorithm with variations 
intended (among other things) to frustrate use of hardware 
implementations of a key search. 

Key is a user's typed password. Salt is a two-character string 
chosen from the set [a-zA-Z0-9./]; this string is used to per- 
turb the hashing algorithm in one of 4096 different ways, after 
which the password is used as the key to encrypt repeatedly a 
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constant string. The returned value points to the encrypted 
password. The first two characters are the salt itself. 

The dessetkey and desjencrypt entries provide (rather primi- 
tive) access to the actual hashing algorithm. The argument of 
desjsetkey is a character array of length 64 containing only 
the characters with numerical value 0 and 1. If this string is 
divided into groups of 8, the low-order bit in each group is 
ignored; this gives a 56-bit key which is set into the machine. 
This is the key that will be used with the hashing algorithm to 
encrypt the string block with the function desjencrypt. 

The argument to the desjencrypt entry is a character array of 
length 64 containing only the characters with numerical value 
0 and 1 . The argument array is modified in place to a similar 
array representing the bits of the argument after having been 
subjected to the hashing algorithm using the key set by 
desjsetkey. If edflag is zero, the argument is encrypted; if 
non-zero, it is decrypted. 

Note that decryption is not provided in the international ver- 
sion of crypt (3X). The international version is the only version 
supplied with System V, as part of the C Programming Utili- 
ties. If decryption is attempted with the international version 
of desjencrypt, an error message is printed. 

Crypt, setkey, and encrypt are front-end routines that invoke 
desjzrypt, des setkey, and desjencrypt respectively. 

DIAGNOSTICS 

In the international version of crypt (3X), a flag argument of 1 
to desjencrypt is not accepted, and an error message is 
printed. 

SEE ALSO 

getpass(3C) , passwd (4) . 

login(1), passwd(1) in the User's Reference Manual. 
CAVEATS 

The return value in crypt points to static data that are overwrit- 
ten by each call. 

Only the international version of crypt (3X) is supplied with Sys- 
tem V. The domestic version is not available. 
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NAME 

curses - terminal screen handling and optimization package 

OVERVIEW 

The curses manual page is organized as follows: 

In SYNOPSIS: 

• Compiling information. 

• Summary of parameters used by curses routines. 

• Alphabetical list of curses routines, showing their 
parameters. 

In DESCRIPTION. 

• An overview of how curses routines should be used. 

In ROUTINES, descriptions of each curses routine are grouped 
under the appropriate topics: 

• Overall Screen Manipulation. 

• Window and Pad Manipulation. 

• Output Routines. 

• Input Routines. 

• Output Options Setting. 

• Input Options Setting. 

• Environment Queries. 

• Soft Label Routines. 

• Low-level Curses Access. 

• Terminfo- Level Manipulations. 

• Termcap Emulation. 

• Miscellaneous. 

• Use of cursor. 

• Obsolete calls. 
Then come sections on: 

• ATTRIBUTES. 
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• FUNCTION KEYS. 

• LINE GRAPHICS. 

SYNOPSIS 

cc [flag ...] file ... -Icurses [library ...] 

#include < curses. h> 

(automatically includes <stdio.h>, <termio.h>, and 
<unctrl.h>). 

The parameters in the following list are not global vari- 
ables, but rather this is a summary of the parameters 
used by the curses library routines. All routines return the 
int values ERR or OK unless otherwise noted. Routines 
that return pointers always return NULL on error. (ERR, 
OK, and NULL are all defined in < curses. h>.) Routines 
that return integers are not listed in the parameter list 
below. 

bool bf 

char **area,*boolnames[], *boolcodes[], 

*boolfnames[], *bp 
char *cap, *capname, codename[2], erasechar, 

♦filename, *fmt 
char *keyname, killchar, *label, *longname 
char *name, *numnames[], *numcodes[], 

*numfnames[] 
char *slk_label, *str, *strnames[], *strcodes[], 

*strfnames[] 

char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type 
chtype attrs, ch, horch, vertch 
FILE *infd, *outfd 
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int begin_x, begin_y, begline, bot, c, col, count 
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, 
fildes 

int (*init( )), labfmt, labnum, line 

int ms, ncols, new, newcol, newrow, nlines, 

numlines 
int oldcol, oldrow, overlay 

int p1, p2, p9, pmincol, pminrow, (*putc( )), row 
int smaxcol, smaxrow, smincol, sminrow, start 
int tenths, top, visibility, x, y 

SCREEN *new, *newterm, *set_term 

TERMINAL *cur_term, *nterm, *oterm 

vajist varglist 

WINDOW *curscr, *dstwin, *initscr, *newpad, 

*newwin, *orig 
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, 

*win 

addch(ch) 

addstr(str) 

attroff(attrs) 

attron(attrs) 

attrset(attrs) 

baudrate() 

beep() 

box(win, vertch, horch) 

cbreak() 

clear () 

clearok(win, bf) 

clrtobotO 

clrtoeolQ 

copywin(srcwin, dstwin, sminrow, smincol, dminrow, 

dmincol, dmaxrow, dmaxcol, overlay) 
curs_set(visibility) 
defprogmode ( ) 
def_shell_mode() 
delcurterm (oterm) 
delayoutput(ms) 
delch() 
deleteln() 
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del win (win) 
doupdate() 
draino(ms) 
echo() 

echochar(ch) 

endwin() 

erase () 

erasechar() 

filter() 

flash () 

flushinp() 

garbagedlines(win, begline, numlines) 

getbegyx(win, y, x) 

getch() 

getmaxyx(win, y, x) 

getstr(str) 

getsyx(y, x) 

getyx(win, y, x) 

half delay (tenths) 

has_ic() 

has_il() 

idlok(win, bf) 

inch() 

initscr() 

insch(ch) 

insertln() 

intrf lush (win, bf) 

isendwin() 

keyname (c) 

keypad (win, bf) 

killcharO 

leaveok(win, bf) 

longnameQ 

meta(win, bf) 

move(y, x) 

mvaddch(y, x, ch) 

mvaddstr(y, x, str) 

mvcur(oldrow, oldcol, newrow, newcol) 
mvdelch(y, x) 
mvgetch(y, x) 
mvgetstr(y, x, str) 
mvsnch(y, y) 
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mvinsch(y, x, ch) 
mvprintw(y, x, fmt [, arg...]) 
mvscanw(y, x, fmt [, arg...]) 
mvwaddch(win, y, x, ch) 
mvwaddstr(win, y, x, str) 
mvwdelch(win, y, x) 
mvwgetch(win, y, x) 
mvwgetstr(win, y, x, str) 
mvwin(win, y, x) 
mvwinch(win, y, x) 
mvwinsch(win, y, x, ch) 
mvwprintw(win, y, x, fmt [, arg . . .]) 
mvwscanw(win, y, x, fmt [, arg...]) 
napms(ms) 
newpad(nlines, ncols) 
newterm(type, outfd, infd) 
newwin(nlines, ncols, begin_y, begin_x) 
nl() 

nocbreak() 
node lay (win, bf) 
noecho() 
nonl() 
noraw() 

notimeout(win, bf) 
overlay(srcwin, dstwin) 
overwrite (srcwin, dstwin) 
pechochar(pad, ch) 

pnoutrefresh(pad, pminrow, pmincol, sminrow, 
smincol, smaxrow, smaxcol) 
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prefresh(pad, pminrow, pmincol, sminrow, smincol, 

smaxrow, smaxcol) 
printw(fmt [, arg...]) 
putp(str) 
raw() 
refresh () 

resetprogmode ( ) 
reset_shell_mode ( ) 
resetty() 

restartterro(term, fildes, errret) 
ripoffline(line, init) 
savetty() 

scanw(fmt [, arg...]) 
scrdump (filename) 
scrjnit(filename) 
scr_restore(filename) 
scroll (win) 
scrollok(win, bf) 
setcurterm (nterm) 
set_term(new) 
setscrreg(top, bot) 
setsyx(y, x) 

setupterm(term, fildes, errret) 

slkclearQ 

slkjnlt(fmt) 

slkjabel(labnum) 

slknoutref resh ( ) 

slk_refresh() 

slk_restore() 

slk_set(labnum, label, fmt) 
slk_touch() 
standend() 
standout () 

subpad(orig, nlines, ncols, begin y, begin x) 

subwin(orig, nlines, ncols, begin y, begin x) 

tgetent(bp, name) 

tgetf lag (codename) 

tgetnum (codename) 

tgetstr (codename, area) 

tgoto(cap, col, row) 

tigetf lag (capname) 

tigetnum (capname) 
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tigetstr(capname) 

touchline(win, start, count) 

touch win (win) 

tparm(str, pi , p2, .... p9) 

tputs(str, count, putc) 

traceoff() 

traceon() 

typeahead (tildes) 

unctrl(c) 

ungetch(c) 

vidattr(attrs) 

vidputs(attrs, putc) 

vwprintw(win, fmt, varglist) 

vwscanwjwin, fmt, varglist) 

waddch(win, ch) 

waddstr(win, str) 

wattroff(win, attrs) 

wattron(win, attrs) 

wattrset(win, attrs) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win) 

wdeleteln(win) 

wechochar(win, ch) 

werase(win) 

wgetch(win) 

wgetstr(win, str) 

winch (win) 

winsch(win, ch) 

winsertln(win) 

wmove(win, y, x) 

wnoutref resh (win) 

wprintw(win, fmt [, arg...]) 

wref resh (win) 

wscanw(win, fmt [, arg...]) 
wsetscrreg(win, top, bot) 
wstandend(win) 
wstandout(win) 

DESCRIPTION 

The curses routines give the user a terminal-independent 
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method of updating screens with reasonable optimization. 

In order to initialize the routines, the routine initscr() or 
newterm() must be called before any of the other routines 
that deal with windows and screens are used. (Three excep- 
tions are noted where they apply.) The routine endwin() must 
be called before exiting. To get character-at-a-time input 
without echoing, (most interactive, screen oriented programs 
want this) after calling initscr() you should call "cbreakQ; 
noechoQ;" Most programs would additionally call "nonl(); 
intrflush (stdscr, FALSE); keypad(stdscr, TRUE);". 

Before a curses program is run, a terminal's tab stops should 
be set and its initialization strings, if defined, must be output. 
This can be done by executing the tput init command after 
the shell environment variable TERM has been exported. For 
further details, see profile (4), fpi/f(1), and the "Tabs and Initial- 
ization" subsection of terminfo{4). 

The curses library contains routines that manipulate data 
structures called windows that can be thought of as two- 
dimensional arrays of characters representing all or part of a 
terminal screen. A default window called stdscr is supplied, 
which is the size of the terminal screen. Others may be 
created with newwin(). Windows are referred to by variables 
declared as WINDOW *; the type WINDOW is defined in 
< curses. h> to be a C structure. These data structures are 
manipulated with routines described below, among which the 
most basic are move() and addch(). (More general versions 
of these routines are included with names beginning with w, 
allowing you to specify a window. The routines not beginning 
with w usually affect stdscr.) Then refresh () is called, telling 
the routines to make the user's terminal screen look like 
stdscr. The characters in a window are actually of type 
chtype, so that other information about the character may 
also be stored with each character. 

Special windows called pads may also be manipulated. These 
are windows which are not constrained to the size of the 
screen and whose contents need not be displayed completely. 
See the description of newpadQ under "Window and Pad 
Manipulation" for more information. 
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In addition to drawing characters on the screen, video attri- 
butes may be included which cause the characters to show up 
in modes such as underlined or in reverse video on terminals 
that support such display enhancements. Line drawing char- 
acters may be specified to be output. On input, curses is also 
able to translate arrow and function keys that transmit escape 
sequences into single values. The video attributes, line draw- 
ing characters, and input values use names, defined in 
<curses.h>, such as A REVERSE, ACS HLIME, and 
KEYLEFT. 

Curses also defines the WINDOW * variable, cursor, which is 
used only for certain low- level operations like clearing and 
redrawing a garbaged screen, cursor can be used in only a 
few routines. If the window argument to clearokQ is cursor, 
the next call to wrefresh() with any window will cause the 
screen to be cleared and repainted from scratch. If the win- 
dow argument to wrefreshQ is cursor, the screen in immedi- 
ately cleared and repainted from scratch. This is how most 
programs would implement a "repaint-screen" function. More 
information on using cursor is provided where its use is 
appropriate. 

The environment variables LINES and COLUMNS may be set 
to override terminfo's idea of how large a screen is. These 
may be used in an AT&T Teletype 5620 layer, for example, 
where the size of a screen is changeable. 

If the environment variable TERMINFO is defined, any pro- 
gram using curses will check for a local terminal definition 
before checking in the standard place. For example, if the 
environment variable TERM is set to att4425, then the com- 
piled terminal definition is found in 
/usr/lib/terminfo/a/att4425. (The a is copied from the first 
letter of att4425 to avoid creation of huge directories.) How- 
ever, if TERMINFO is set to $HOME/myterms, curses will first 
check $HOME/myterms/a/att4425, and, if that fails, will then 
check /usr/lib/terminfo/a/att4425. This is useful for develop- 
ing experimental definitions or when write permission on 
/usr/lib/terminfo is not available. 

The integer variables LINES and COLS are defined in 
<curses.h>, and will be filled in by initscrQ with the size of 
the screen. (For more information, see the subsection 
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"Terminfo- Level Manipulations.") The constants TRUE and 
FALSE have the values 1 and 0, respectively. The constants 
ERR and OK are returned by routines to indicate whether the 
routine successfully completed. These constants are also 
defined in < curses.h > . 

ROUTINES 

Many of the following routines have two or more versions. 
The routines prefixed with w require a window argument. The 
routines prefixed with p require a pad argument. Those 
without a prefix generally use stdscr. 

The routines prefixed with mv require y and x coordinates to 
move to before performing the appropriate action. The mv() 
routines imply a call to move() before the call to the other 
routine. The window argument is always specified before the 
coordinates. Y always refers to the row (of the window) , and x 
always refers to the column. The upper left corner is always 
(0,0), not (1,1). The routines prefixed with mvw take both a 
window argument and y and x coordinates. 

In each case, win is the window affected and pad is the pad 
affected, (win and pad are always of type WINDOW *.) 
Option-setting routines require a boolean flag bf with the value 
TRUE or FALSE, {bf is always of type bool.) The types WIN- 
DOW, bool, and chtype are defined in < curses.h > . See the 
SYNOPSIS for a summary of what types all variables are. 

All routines return either the integer ERR or the integer OK, 
unless otherwise noted. Routines that return pointers always 
return NULL on error. 
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Overall Screen Manipulation 
WINDOW *initscr() 

The first routine called should almost always be 
initscrQ. (The exceptions are slk_init(), filterQ, and 
ripofflineQ.) This will determine the terminal type and 
initialize all curses data structures. InitscrQ also 
arranges that the first call to refresh () will clear the 
screen. If errors occur, initscrQ will write an appropri- 
ate error message to standard error and exit; otherwise, 
a pointer to stdscr is returned. If the program wants 
an indication of error conditions, newterm() should be 
used instead of initscr(). initscrQ should only be 
called once per application. 

end win Q 

A program should always call endwin() before exiting 
or escaping from curses mode temporarily, to do a 
shell escape or system (3S) call, for example. This rou- 
tine will restore tty{7) modes, move the cursor to the 
lower left corner of the screen and reset the terminal 
into the proper non-visual mode. To resume after a 
temporary escape, call wrefreshQ or doupdateQ. 

isendwinQ 

Returns TRUE if end win Q has been called without any 
subsequent calls to wrefreshQ. 

SCREEN *newterm(type, outfd, infd) 

A program that outputs to more than one terminal must 
use newtermQ for each terminal instead of initscrQ. A 
program that wants an indication of error conditions, so 
that it may continue to run in a line-oriented mode if the 
terminal cannot support a screen-oriented program, 
must also use this routine. NewtermQ should be called 
once for each terminal. It returns a variable of type 
SCREEN* that should be saved as a reference to that 
terminal. The arguments are the type of the terminal to 
be used in place of the environment variable TERM; 
outfd, a stdio (3S) file pointer for output to the terminal; 
and infd, another file pointer for input from the terminal. 
When it is done running, the program must also call 
endwinQ for each terminal being used. If newtermQ is 
called more than once for the same terminal, the first 



UP-13712.3 



Page 1 1 



CURSES(3X) 



terminal referred to must be the last one for which 
endwin() is called. 

SCREEN *set_term(new) 

This routine is used to switch between different termi- 
nals. The screen reference new becomes the new 
current terminal. A pointer to the screen of the previ- 
ous terminal is returned by the routine. This is the only 
routine which manipulates SCREEN pointers; all other 
routines affect only the current terminal. 

Window and Pad Manipulation 
refresh () 
wrefresh (win) 

These routines [or prefresh(), pnoutrefresh(), 
wnoutrefresh(), or doupdateQ] must be called to write 
output to the terminal, as most other routines merely 
manipulate data structures. Wrefresh () copies the 
named window to the physical terminal screen, taking into 
account what is already there in order to minimize the 
amount of information that is sent to the terminal (called 
optimization). Refresh () does the same thing, except it 
uses stdscr as a default window. Unless leaveok() has 
been enabled, the physical cursor of the terminal is left at 
the location of the window's cursor. The number of char- 
acters output to the terminal is returned. 

Note that refresh () is a macro. 
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wnoutref resh (win) 
doupdate() 

These two routines allow multiple updates to the physical 
terminal screen with more efficiency than wrefreshQ 
alone. How this is accomplished is described in the next 
paragraph. 

Curses keeps two data structures representing the termi- 
nal screen: a physical terminal screen, describing what is 
actually on the screen, and a virtual terminal screen, 
describing what the programmer wants to have on the 
screen. WrefreshQ works by first calling wnoutrefreshQ, 
which copys the named window to the virtual screen, and 
then by calling doupdate(), which compares the virtual 
screen to the physical screen and does the actual update. 
If the programmer wishes to output several windows at 
once, a series of calls to wrefreshQ will result in alternat- 
ing calls to wnoutrefresh() and doupdate(), causing 
several bursts of output to the screen. By first calling 
wnoutrefresh() for each window, it is then possible to call 
doupdate() once, resulting in only one burst of output, 
with probably fewer total characters transmitted and cer- 
tainly less processor time used. 

WINDOW *newwin(nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a new window with the 
given number of lines (or rows), nlines, and columns, 
ncols. The upper left corner of the window is at line 
begin_y, column beginx. If either nlines or ncols is 0, 
they will be set to the value of \\nes-begin_y and 
co\s-begin_x. A new full-screen window is created by cal- 
ling newwin(0,0,0,0). 

mvwin(win, y, x) 

Move the window so that the upper left corner will be at 
position (y, x). If the move would cause the window to be 
off the screen, it is an error and the window is not moved. 

WINDOW *subwin(orig, nlines, ncols, beginy, begin_x) 

Create and return a pointer to a new window with the 
given number of lines (or rows), nlines, and columns, 
ncols. The window is at position (beginy, begin _x) on 
the screen. (This position is relative to the screen, and 
not to the window orig.) The window is made in the 
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middle of the window orig, so that changes made to one 
window will affect both windows. When using this routine, 
often it will be necessary to call touch win Q or touchlineQ 
on orig before calling wrefreshQ. 

delwin(win) 

Delete the named window, freeing up all memory associ- 
ated with it. In the case of overlapping windows, subwin- 
dows should be deleted before the main window. 

WINDOW *newpad(nlines, ncols) 

Create and return a pointer to a new pad data structure 
with the given number of lines (or rows), nlines, and 
columns, ncols. A pad is a window that is not restricted 
by the screen size and is not necessarily associated with a 
particular part of the screen. Pads can be used when a 
large window is needed, and only a part of the window 
will be on the screen at one time. Automatic refreshes of 
pads (for example, from scrolling or echoing of input) do 
not occur. It is not legal to call wrefreshQ with a pad as 
an argument; the routines prefreshQ or pnoutrefresh() 
should be called instead. Note that these routines require 
additional parameters to specify the part of the pad to be 
displayed and the location on the screen to be used for 
display. 

WINDOW *subpad(orig, nlines, ncols, begin_y, begin_x) 

Create and return a pointer to a subwindow within a pad 
with the given number of lines (or rows), nlines, and 
columns, ncols. Unlike subwinQ, which uses screen coor- 
dinates, the window is at position (begin_y, begin_x) on 
the pad. The window is made in the middle of the win- 
dow orig, so that changes made to one window will affect 
both windows. When using this routine, often it will be 
necessary to call touchwinQ or touchlineQ on orig 
before calling prefreshQ. 

prefresh(pad, pminrow, pmincol, sminrow, smincol, 

smaxrow, smaxcol) 
pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, 
smaxrow, smaxcol) 
These routines are analogous to wrefreshQ and 
wnoutrefreshQ except that pads, instead of windows, are 
involved. The additional parameters are needed to 
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indicate what part of the pad and screen are involved. 
pminrow and pmincol specify the upper left corner, in the 
pad, of the rectangle to be displayed, sminrow, smincol, 
smaxrow, and smaxcol specify the edges, on the screen, 
of the rectangle to be displayed in. The lower right corner 
in the pad of the rectangle to be displayed is calculated 
from the screen coordinates, since the rectangles must be 
the same size. Both rectangles must be entirely con- 
tained within their respective structures. Negative values 
of pminrow, pmincol, sminrow, or smincol are treated as 
if they were zero. 

Output Routines 

These routines are used to "draw" text on windows. 

addch(ch) 

waddch(win, ch) 

mvaddch(y, x, ch) 

mvwaddch(win, y, x, ch) 

The character ch is put into the window at the current cur- 
sor position of the window and the position of the window 
cursor is advanced. Its function is similar to that of 
putchar [see pi/fc(3S)]. At the right margin, an automatic 
newline is performed. At the bottom of the scrolling 
region, if scrollok() is enabled, the scrolling region will be 
scrolled up one line. 

If ch is a tab, newline, or backspace, the cursor will be 
moved appropriately within the window. A newline also 
does a clrtoeol() before moving. Tabs are considered to 
be at every eighth column. If ch is another control char- 
acter, it will be drawn in the "X notation. (Calling winch () 
after adding a control character will not return the control 
character, but instead will return the representation of the 
control character.) 

Video attributes can be combined with a character by 
OR-ing them into the parameter. This will result in these 
attributes also being set. (The intent here is that text, 
including attributes, can be copied from one place to 
another using inch() and addchQ.) See standout(), 
below. 

Note that ch is actually of type chtype, not a character. 
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Note that addch(), mvaddchQ, and mvwaddch(), are 
macros. 

echochar(ch) 

wechochar(win, ch) 

pechochar(pad, ch) 

These routines are functionally equivalent to a call to 
addch(ch) followed by a call to refresh (), a call to 
waddch(win, ch) followed by a call to wrefresh(win), or a 
call to waddch(pad, ch) followed by a call to 
prefresh(pad). The knowledge that only a single charac- 
ter is being output is taken into consideration and, for 
non-control characters, a considerable performance gain 
can be seen by using these routines instead of their 
equivalents. In the case of pechochar(), the last location 
of the pad on the screen is reused for the arguments to 
prefreshQ. 

Note that ch is actually of type chtype, not a character. 
Note that echocharQ is a macro. 

addstr(str) 

waddstr(win, str) 

mvwaddstr(win, y, x, str) 

mvaddstr(y, x, str) 

These routines write all the characters of the null- 
terminated character string str on the given window. This 
is equivalent to calling waddch() once for each character 
in the string. 

Note that addstr(), mvaddstrQ, and mvwaddstrQ are 
macros. 

attroff(attrs) 
wattroff(win, attrs) 
attron(attrs) 
wattron(win, attrs) 
attrset(attrs) 
wattrset(win, attrs) 
standend() 
wstandend(win) 
standout () 
wstandout(win) 

These routines manipulate the current attributes of the 
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named window. These attributes can be any combination 
of ASTANDOUT, AREVERSE, ABOLD, ADIM, 
A BLINK, AUNDERLINE, and A ALTCHARSET. These 
constants are defined in <curses.h> and can be com- 
bined with the C logical OR ( j ) operator. 

The current attributes of a window are applied to all char- 
acters that are written into the window with waddchQ. 
Attributes are a property of the character, and move with 
the character through any scrolling and insert/delete 
line/character operations. To the extent possible on the 
particular terminal, they will be displayed as the graphic 
rendition of the characters put on the screen. 
Attrset(attrs) sets the current attributes of the given win- 
dow to attrs. Attroff(attrs) turns off the named attributes 
without turning on or off any other attributes, 
attron (attrs) turns on the named attributes without affect- 
ing any others. Standout () is the same as 
attron ( AST AN DOUT). StandendQ is the same as 
attrset(O), that is, it turns off all attributes. 

Note that attrs is actually of type chtype, not a character. 

Note that attroff(), attron (), attrset(), standend(), and 
standout () are macros. 

beep() 
flash () 

These routines are used to signal the terminal user. 
Beep() will sound the audible alarm on the terminal, if 
possible, and if not, will flash the screen (visible bell), if 
that is possible. Flash () will flash the screen, and if that 
is not possible, will sound the audible signal. If neither 
signal is possible, nothing will happen. Nearly all termi- 
nals have an audible signal (bell or beep) but only some 
can flash the screen. 

box(win, vertch, horch) 

A box is drawn around the edge of the window, win. 
vertch and horch are the characters the box is to be 
drawn with. If vertch and horch are 0, then appropriate 
default characters, ACS_VLINE and ACS HLINE, will be 
used. 

Note that vertch and horch are actually of type chtype, 



UP-13712.3 



Page 17 



CURSES (3X) 



not characters. 

erase () 
werase(win) 

These routines copy blanks to every position in the win- 
dow. 

Note that eraseQ is a macro. 

clear () 
wclear(win) 

These routines are like erase() and weraseQ, but they 
also call clearokQ, arranging that the screen will be 
cleared completely on the next call to wrefresh() for that 
window, and repainted from scratch. 

Note that clear() is a macro. 

clrtobotO 
wclrtobot(win) 

All lines below the cursor in this window are erased. Also, 
the current line to the right of the cursor, inclusive, is 
erased. 

Note that clrtobotQ is a macro. 

clrtoeol() 
wclrtoeol(win) 

The current line to the right of the cursor, inclusive, is 
erased. 

Note that clrtoeol() is a macro. 

delayoutput(ms) 

Insert a ms millisecond pause in the output. It is not 
recommended that this routine be used extensively, 
because padding characters are used rather than a pro- 
cessor pause. 

delch() 

wdelch(win) 

mvdelch(y, x) 

mvwdelch(win, y, x) 

The character under the cursor in the window is deleted. 
All characters to the right on the same line are moved to 
the left one position and the last character on the line is 
filled with a blank. The cursor position does not change 
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(after moving to (y, x), if specified). (This does not imply 
use of the hardware "delete-character" feature.) 

Note that delchQ, mvdelchQ, and mvwdelch() are mac- 
ros. 

deleteln() 

wdeleteln(win) 

The line under the cursor in the window is deleted. All 
lines below the current line are moved up one line. The 
bottom line of the window is cleared. The cursor position 
does not change. (This does not imply use of the 
hardware "delete-line" feature.) 

Note that deleteln() is a macro. 

getyx(win, y, x) 

The cursor position of the window is placed in the two 
integer variables y and x. This is implemented as a 
macro, so no "&" is necessary before the variables. 

getbegyx(win, y, x) 

getmaxyx(win, y, x) 

Like getyxj), these routines store the current beginning 
coordinates and size of the specified window. 

Note that getbegyx() and getmaxyx() are macros. 

insch(ch) 

winsch(win, ch) 

mvwinsch(win, y, x, ch) 

mvinsch(y, x, ch) 

The character ch is inserted before the character under 
the cursor. All characters to the right are moved one 
space to the right, possibly losing the rightmost character 
of the line. The cursor position does not change (after 
moving to (y, x), if specified). (This does not imply use of 
the hardware "insert-character" feature.) 

Note that ch is actually of type chtype, not a character. 

Note that inschQ, mvinschQ, and mvwinsch() are mac- 
ros. 

insertln() 
winsertln(win) 

A blank line is inserted above the current line and the 
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bottom line is lost. (This does not imply use of the 
hardware "insert-line" feature.) 

Note that insertln() is a macro. 

move(y, x) 

wmove(win, y, x) 

The cursor associated with the window is moved to line 
(row) y, column x. This does not move the physical cur- 
sor of the terminal until refresh() is called. The position 
specified is relative to the upper left corner of the window, 
which is (0, 0). 

Note that move() is a macro. 

overlay(srcwin, dstwin) 

overwrite(srcwin, dstwin) 

These routines overlay srcwin on top of dstwin; that is, all 
text in srcwin is copied into dstwin. scrwin and dstwin 
need not be the same size; only text where the two win- 
dows overlap is copied. The difference is that overlay () is 
non-destructive (blanks are not copied), while overwQ is 
destructive. 

copywin (srcwin, dstwin, sminrow, smincol, dminrow, 
dmincol, dmaxrow, dmaxcol, overlay) 
This routine provides a finer grain of control over the 
overlay () and overwrite () routines. Like in the 
prefreshQ routine, a rectangle is specified in the destina- 
tion window, (dminrow, dmincol) and (dmaxrow, dmaxcol), 
and the upper-left-corner coordinates of the source win- 
dow, (sminrow, smincol). If the argument overlay is true, 
then copying is non-destructive, as in overlayQ. 

printw(fmt [, arg . . .]) 

wprintw(win, fmt [, arg . . .]) 

mvprintw(y, x, fmt [, arg . . .]) 

mvwprintw(win, y, x, fmt [, arg...]) 

These routines are analogous to printf(3S). The string 
which would be output by printf(3S) is instead output 
using waddstrQ on the given window. 

vwprintw(win, fmt, varglist) 

This routine corresponds to vfprintf [see vprintf (3S)]. It 
performs a wprintwQ using a variable argument list. The 
third argument is a vajist, a pointer to a list of 



Page 20 



UP-13712.3 



CURSES (3X) 



arguments, as defined in <varargs.h>. See the 
vprintf (3S) and varargs(5) manual pages for a detailed 
description on how to use variable argument lists. 

scroll (win) 

The window is scrolled up one line. This involves moving 
the lines in the window data structure. As an optimiza- 
tion, if the window is stdscr and the scrolling region is the 
entire window, the physical screen will be scrolled at the 
same time. 

touch win (win) 

touchline(win, start, count) 

Throw away all optimization information about which parts 
of the window have been touched, by pretending that the 
entire window has been drawn on. This is sometimes 
necessary when using overlapping windows, since a 
change to one window will affect the other window, but 
the records of which lines have been changed in the other 
window will not reflect the change. Touchline() only pre- 
tends that count lines have been changed, beginning with 
line start . 
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Input Routines 

getch() 

wgetch(win) 

mvgetch(y, x) 

mvwgetch(win, y, x) 

A character is read from the terminal associated with the 
window. In NODELAY mode, if there is no input waiting, 
the value ERR is returned. In DELAY mode, the program 
will hang until the system passes text through to the pro- 
gram. Depending on the setting of cbreakQ, this will be 
after one character (CBREAK mode), or after the first 
newline (NOCBREAK mode). In HALF-DELAY mode, the 
program will hang until a character is typed or the speci- 
fied timeout has been reached. Unless noecho() has 
been set, the character will also be echoed into the desig- 
nated window. No refresh () will occur between the 
move() and the getch() done within the routines 
mvgetch() and mvwgetch(). 

When using getch(), wgetchQ, mvgetch(), or 
mvwgetch(), do not set both NOCBREAK mode [noc- 
breakQ] and ECHO mode [echoQ] at the same time. 
Depending on the state of the tty(7) driver when each 
character is typed, the program may produce undesirable 
results. 

If keypad(win, TRUE) has been called, and a function key 
is pressed, the token for that function key will be returned 
instead of the raw characters. (See keypad () under 
"Input Options Setting.") Possible function keys are 
defined in < curses. h> with integers beginning with 
0401, whose names begin with KEY_. If a character is 
received that could be the beginning of a function key 
(such as escape), curses will set a timer. If the remainder 
of the sequence is not received within the designated 
time, the character will be passed through, otherwise the 
function key value will be returned. For this reason, on 
many terminals, there will be a delay after a user presses 
the escape key before the escape is returned to the pro- 
gram. (Use by a programmer of the escape key for a sin- 
gle character routine is discouraged. Also see 
notimeout() below.) 
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Note that getch(), mvgetch(), and mvwgetch() are mac- 
ros. 

getstr(str) 

wgetstr(win, str) 

mvgetstr(y, x, str) 

mvwgetstr(win, y, x, str) 

A series of calls to getchQ is made, until a newline, car- 
riage return, or enter key is received. The resulting value 
is placed in the area pointed at by the character pointer 
str. The user's erase and kill characters are interpreted. 
As in mvgetch(), no refresh () is done between the 
move() and getstr() within the routines mvgetstrQ and 
mvwgetstr(). 

Note that getstr(), mvgetstr(), and mvwgetstrQ are mac- 
ros. 

flushinpQ 

Throws away any typeahead that has been typed by the 
user and has not yet been read by the program. 

ungetch(c) 

Place c back onto the input queue to be returned by the 
next call to wgetchQ. 

inch() 

winch (win) 

mvinch(y, x) 

mvwinch(win, y, x) 

The character, of type chtype, at the current position in 
the named window is returned. If any attributes are set 
for that position, their values will be OR'ed into the value 
returned. The predefined constants A_CHARTEXT and 
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A_ATTRIBUTES, defined in <curses.h>, can be used 
with the C logical AND (&) operator to extract the charac- 
ter or attributes alone. 

Note that inch(), winchQ, mvinchQ, and mvwinch() are 
macros. 

scanw(fmt [, arg. . .]) 

wscanw(win, fmt [, arg . . .]) 

mvscanw(y, x, fmt [, arg...]) 

mvwscanw(win, y, x, fmt [, arg . . .]) 

These routines correspond to scant (3S), as do their argu- 
ments and return values. Wgetstr() is called on the win- 
dow, and the resulting line is used as input for the scan. 

vwscanw(win, fmt, ap) 

This routine is similar to vwprintwQ above in that per- 
forms a wscanw() using a variable argument list. The 
third argument is a vajist, a pointer to a list of argu- 
ments, as defined in <varargs.h>. See the vprintf (3S) 
and varargs (5) manual pages for a detailed description on 
how to use variable argument lists. 

Output Options Setting 

These routines set options within curses that deal with output. 
All options are initially FALSE, unless otherwise stated. It is 
not necessary to turn these options off before calling 
endwin(). 

clearok(win, bf) 

If enabled (bf is TRUE ), the next call to wrefreshQ with 
this window will clear the screen completely and redraw 
the entire screen from scratch. This is useful when the 
contents of the screen are uncertain, or in some cases for 
a more pleasing visual effect. 

idlok(win, bf) 

If enabled (bf is TRUE), curses will consider using the 
hardware "insert/delete-line" feature of terminals so 
equipped. If disabled {bf is FALSE), curses will very sel- 
dom use this feature. (The "insert/delete-character" 
feature is always considered.) This option should be 
enabled only if your application needs "insert/delete-line", 
for example, for a screen editor. It is disabled by default 
because "insert/delete-line" tends to be visually annoying 
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when used in applications where it isn't really needed. If 
"insert/delete-line" cannot be used, curses will redraw the 
changed portions of all lines. 

leaveok(win, bf) 

Normally, the hardware cursor is left at the location of the 
window cursor being refreshed. This option allows the 
cursor to be left wherever the update happens to leave it. 
It is useful for applications where the cursor is not used, 
since it reduces the need for cursor motions. If possible, 
the cursor is made invisible when this option is enabled. 

setscrreg(top, bot) 

wsetscrreg(win, top, bot) 

These routines allow the user to set a software scrolling 
region in a window, top and bot are the line numbers of 
the top and bottom margin of the scrolling region. (Line 0 
is the top line of the window.) If this option and scrol- 
lok() are enabled, an attempt to move off the bottom 
margin line will cause all lines in the scrolling region to 
scroll up one line. (Note that this has nothing to do with 
use of a physical scrolling region capability in the terminal, 
like that in the DEC VT100. Only the text of the window is 
scrolled; if idlokQ is enabled and the terminal has either a 
scrolling region or "insert/delete-line" capability, they will 
probably be used by the output routines.) 

Note that setscrreg() and wsetscrreg() are macros. 

scrollok(win, bf) 

This option controls what happens when the cursor of a 
window is moved off the edge of the window or scrolling 
region, either from a newline on the bottom line, or typing 
the last character of the last line. If disabled (bf is 
FALSE), the cursor is left on the bottom line at the loca- 
tion where the offending character was entered. If 
enabled (bf is TRUE), wrefreshQ is called on the window, 
and then the physical terminal and window are scrolled up 
one line. (Note that in order to get the physical scrolling 
effect on the terminal, it is also necessary to call idlok().) 

nl() 
nonl() 

These routines control whether newline is translated into 
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carriage return and linefeed on output, and whether 
return is translated into newline on input. Initially, the 
translations do occur. By disabling these translations 
using nonl(), curses is able to make better use of the 
linefeed capability, resulting in faster cursor motion. 

Input Options Setting 

These routines set options within curses that deal with input. 
The options involve using ioctl(2) and therefore interact with 
curses routines. It is not necessary to turn these options off 
before calling endwin(). 

For more information on these options, see "curses/terminfo" 
in the System V Programmer's Guide. 

cbreak() 
nocbreakQ 

These two routines put the terminal into and out of 
CBREAK mode, respectively. In CBREAK mode, charac- 
ters typed by the user are immediately available to the 
program and erase/kill character processing is not per- 
formed. When in NOCBREAK mode, the tty driver will 
buffer characters typed until a newline or carriage return 
is typed. Interrupt and flow-control characters are unaf- 
fected by this mode [see termio{7)]. Initially the terminal 
may or may not be in CBREAK mode, as it is inherited, 
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therefore, a program should call cbreak() or nocbreak() 
explicitly. Most interactive programs using curses will set 
CBREAK mode. 

Note that cbreak() overrides raw(). See getch() under 
"Input Routines" for a discussion of how these routines 
interact with echo() and noecho(). 

echo() 
noecho() 

These routines control whether characters typed by the 
user are echoed by getchQ as they are typed. Echoing 
by the tty driver is always disabled, but initially getchQ is 
in ECHO mode, so characters typed are echoed. Authors 
of most interactive programs prefer to do their own echo- 
ing in a controlled area of the screen, or not to echo at all, 
so they disable echoing by calling noechoQ. See getchQ 
under "Input Routines" for a discussion of how these rou- 
tines interact with cbreak() and nocbreak(). 

halfdelay(tenths) 

Half-delay mode is similar to CBREAK mode in that char- 
acters typed by the user are immediately available to the 
program. However, after blocking for tenths tenths of 
seconds, ERR will be returned if nothing has been typed. 
tenths must be a number between 1 and 255. Use noc- 
breakQ to leave half- delay mode. 

intrf lush (win, bf) 

If this option is enabled, when an interrupt key is pressed 
on the keyboard (interrupt, break, quit) all output in the 
tty driver queue will be flushed, giving the effect of faster 
response to the interrupt, but causing curses to have the 
wrong idea of what is on the screen. Disabling the option 
prevents the flush. The default for the option is inherited 
from the tty driver settings. The window argument is 
ignored. 

keypad (win, bf) 

This option enables the keypad of the user's terminal. If 
enabled, the user can press a function key (such as an 
arrow key) and wgetchQ will return a single value 
representing the function key, as in KEY_LEFT. If dis- 
abled, curses will not treat function keys specially and the 
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program would have to interpret the escape sequences 
itself. If the keypad in the terminal can be turned on 
(made to transmit) and off (made to work locally), turning 
on this option will cause the terminal keypad to be turned 
on when wgetch() is called. 

meta(win, bf) 

If enabled, characters returned by wgetchQ are transmit- 
ted with all 8 bits, instead of with the highest bit stripped. 
In order for meta() to work correctly, the km 
(has_meta_key) capability has to be specified in the 
terminal's terminfo(4) entry. 

nodelay(win, bf) 

This option causes wgetch() to be a non-blocking call. If 
no input is ready, wgetch() will return ERR. If disabled, 
wgetch() will hang until a key is pressed. 

notimeout(win, bf) 

While interpreting an input escape sequence, wgetchQ 
will set a timer while waiting for the next character. If 
notimeout(win, TRUE) is called, then wgetchQ will not set 
a timer. The purpose of the timeout is to differentiate 
between sequences received from a function key and 
those typed by a user. 

rawQ 
norawQ 

The terminal is placed into or out of raw mode. RAW 
mode is similar to CBREAK mode, in that characters 
typed are immediately passed through to the user pro- 
gram. The differences are that in RAW mode, the inter- 
rupt, quit, suspend, and flow control characters are 
passed through uninterpreted, instead of generating a 
signal. RAW mode also causes 8-bit input and output. 
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The behavior of the BREAK key depends on other bits in 
the tty(7) driver that are not set by curses. 

typeahead(fildes) 

Curses does "line-breakout optimization" by looking for 
typeahead periodically while updating the screen. If input 
is found, and it is coming from a tty, the current update 
will be postponed until refresh () or doupdate() is called 
again. This allows faster response to commands typed in 
advance. Normally, the file descriptor for the input FILE 
pointer passed to newterm(), or stdin in the case that 
initscrQ was used, will be used to do this typeahead 
checking. The typeahead () routine specifies that the file 
descriptor fildes is to be used to check for typeahead 
instead. If fildes is -1, then no typeahead checking will be 
done. 

Note that fildes is a file descriptor, not a < stdio.h > FILE 
pointer. 

Environment Queries 
baud r ate () 

Returns the output speed of the terminal. The number 
returned is in bits per second, for example, 9600, and is 
an integer. 

char erasechar() 

The user's current erase character is returned. 

has_ic() 

True if the terminal has insert- and delete-character capa- 
bilities. 

has_il() 

True if the terminal has insert- and delete-line capabilities, 
or can simulate them using scrolling regions. This might 
be used to check to see if it would be appropriate to turn 
on physical scrolling using scrollokQ. 

char killchar() 

The user's current line-kill character is returned. 
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char *longname() 

This routine returns a pointer to a static area containing a 
verbose description of the current terminal. The max- 
imum length of a verbose description is 128 characters. It 
is defined only after the call to initscrQ or newtermQ. 
The area is overwritten by each call to newtermQ and is 
not restored by set_term(), so the value should be saved 
between calls to newtermQ if longnameQ is going to be 
used with multiple terminals. 

Soft Label Routines 

If desired, curses will manipulate the set of soft function-key 
labels that exist on many terminals. For those terminals that 
do not have soft labels, if you want to simulate them, curses 
will take over the bottom line of stdscr, reducing the size of 
stdscr and the variable LINES. Curses standardizes on 8 
labels of 8 characters each. 

slkjnit(labfmt) 

In order to use soft labels, this routine must be called 
before initscrQ or newtermQ is called. If initscrQ winds 
up using a line from stdscr to emulate the soft labels, 
then labfmt determines how the labels are arranged on 
the screen. Setting labfmt to indicates that the labels are 
to be arranged in a 3-2-3 arrangement; 1 asks for a 4-4 
arrangement. 

slk_set(labnum, label, labfmt) 

Labnum is the label number, from 1 to 8. Label is the 
string to be put on the label, up to 8 characters in length. 
A NULL string or a NULL pointer will put up a blank label. 
labfmt is one of 0, 1 or 2, to indicate whether the label is 
to be left-justified, centered, or right-justified within the 
label. 

slk_refresh() 
slk_noutrefresh() 

These routines correspond to the routines wrefreshQ and 
wnoutrefreshQ. Most applications would use 
slk_noutrefresh() because a wrefreshQ will most likely 
soon follow. 

char *slk_label (labnum) 

The current label for label number labnum, with leading 
and trailing blanks stripped, is returned. 
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slk_clear() 

The soft labels are cleared from the screen. 
slk_restore() 

The soft labels are restored to the screen after a 
slk_clear(). 

slk_touch() 

All of the soft labels are forced to be output the next time 
a slk_noutrefresh() is performed. 

Low- Level curses Access 

The following routines give low-level access to various curses 
functionality. These routines typically would be used inside of 
library routines. 

defprogmode ( ) 
defshel Imode ( ) 

Save the current terminal modes as the "program" (in 
curses) or "shell" (not in curses) state for use by the 
reset_prog_mode() and reset_shell_mode() routines. 
This is done automatically by initscr(). 

resetprogmode ( ) 
reset_shell_mode ( ) 

Restore the terminal to "program" (in curses) or "shell" 
(out of curses) state. These are done automatically by 
endwin() and doupdate() after an endwin(), so they nor- 
mally would not be called. 

resetty() 
savetty() 

These routines save and restore the state of the terminal 
modes. SavettyQ saves the current state of the terminal 
in a buffer and resetty() restores the state to what it was 
at the last call to savetty(). 

getsyx(y, x) 

The current coordinates of the virtual screen cursor are 
returned in y and x. Like getyxQ, the variables y and x do 
not take an "&" before them. If leaveokQ is currently 
TRUE, then -1,-1 will be returned. If lines may have been 
removed from the top of the screen using ripoffline() and 
the values are to be used beyond just passing them on to 
setsyxQ, the value y + stdscr- > _yoffset should be used 
for those other uses. 
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Note that getsyx() is a macro. 
setsyx(y, x) 

The virtual screen cursor is set to y, x. If y and x are both 
-1, then leaveokQ will be set. The two routines getsyx() 
and setsyx() are designed to be used by a library routine 
which manipulates curses windows but does not want to 
mess up the current position of the program's cursor. 
The library routine would call getsyxQ at the beginning, 
do its manipulation of its own windows, do a 
wnoutrefresh() on its windows, call setsyx(), and then 
call doupdate(). 

ripoffline(line, init) 

This routine provides access to the same facility that 
slk_init() uses to reduce the size of the screen. Ripoff- 
line() must be called before initscr() or newterm() is 
called. If line is positive, a line will be removed from the 
top of stdscr; if negative, a line will be removed from the 
bottom. When this is done inside initscr(), the routine 
init() is called with two arguments: a window pointer to 
the 1-line window that has been allocated and an integer 
with the number of columns in the window. Inside this ini- 
tialization routine, the integer variables LINES and COLS 
(defined in <curses.h>) are not guaranteed to be accu- 
rate and wrefresh() or doupdateQ must not be called. It 
is allowable to call wnoutrefresh() during the initialization 
routine. 

RipofflineQ can be called up to five times before calling 
initscr() or newterm(). 

scr_dump (filename) 

The current contents of the virtual screen are written to 
the file filename. 

scr_restore (filename) 

The virtual screen is set to the contents of filename, which 
must have been written using scr_dump(). The next call 
to doupdateQ will restore the screen to what it looked like 
in the dump file. 

scrjnit(filename) 

The contents of filename are read in and used to initialize 
the curses data structures about what the terminal 
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currently has on its screen. If the data is determined to 
be valid, curses will base its next update of the screen on 
this information rather than clearing the screen and start- 
ing from scratch. Scr_init() would be used after initscrQ 
or a system (3S) call to share the screen with another pro- 
cess which has done a scr_dump() after its endwin() call. 
The data will be declared invalid if the time-stamp of the 
tty is old or the terminfo (4) capability nrrmc is true. 

curs_set(visibility) 

The cursor is set to invisible, normal, or very visible for 
visibility equal to 0, 1 or 2. 

draino(ms) 

Wait until the output has drained enough that it will only 
take ms more milliseconds to drain completely. 

garbagedlines(win, begline, numlines) 

This routine indicates to curses that a screen line is gar- 
baged and should be thrown away before having any- 
thing written over the top of it. It could be used for pro- 
grams such as editors which want a command to redraw 
just a single line. Such a command could be used in 
cases where there is a noisy communications line and 
redrawing the entire screen would be subject to even 
more communication noise. Just redrawing the single line 
gives some semblance of hope that it would show up 
unblemished. The current location of the window is used 
to determine which lines are to be redrawn. 

napms(ms) 

Sleep for ms milliseconds. 

Terminfo- Level Manipulations 

These low-level routines must be called by programs that 
need to deal directly with the terminfo (4) database to handle 
certain terminal capabilities, such as programming function 
keys. For all other functionality, curses routines are more suit- 
able and their use is recommended. 

Initially, setupterm() should be called. (Note that setuptermQ 
is automatically called by initscrQ and newtermQ.) This will 
define the set of terminal-dependent variables defined in the 
terminfo (4) database. The terminfo (4) variables lines and 
columns [see terminfo (4)] are initialized by setuptermQ as 
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follows: if the environment variables LINES and COLUMNS 
exist, their values are used. Otherwise, the values for lines 
and columns specified in the terminfo(4) database are used. 

The header files <curses.h> and <term.h> should be 
included, in this order, to get the definitions for these strings, 
numbers, and flags. Parameterized strings should be passed 
through tparmQ to instantiate them. All terminfo(4) strings 
[including the output of tparmQ] should be printed with 
tputs() or putp(). Before exiting, reset_shell_mode() should 
be called to restore the tty modes. Programs which use cur- 
sor addressing should output enter_ca_mode upon startup 
and should output exit_ca_mode before exiting [see ter- 
minfo(4)]. (Programs desiring shell escapes should call 
reset_shell_mode() and output exit_ca_mode before the shell 
is called and should output enter_ca_mode and call 
reset_prog_mode() after returning from the shell. Note that 
this is different from the curses routines [see endwinQ]. 

setupterm(term, fildes, errret) 

Reads in the terminfo{4) database, initializing the ter- 
minfo(4) structures, but does not set up the output viril- 
ization structures used by curses. The terminal type is in 
the character string term; if term is NULL, the environ- 
ment variable TERM will be used. All output is to the file 
descriptor fildes. If errret is not NULL, then setuptermQ 
will return OK or ERR and store a status value in the 
integer pointed to by errret. A status of 1 in errret is nor- 
mal, 0 means that the terminal could not be found, and -1 
means that the terminfo{4) database could not be found. 
If errret is NULL, setuptermQ will print an error message 
upon finding an error and exit. Thus, the simplest call is 
setupterm ((char *)0, 1, (int *)0), which uses all the 
defaults. 

The terminfo{4) boolean, numeric, and string variables are 
stored in a structure of type TERMINAL. After setup- 
term () returns successfully, the variable cur_term (of type 
TERMINAL *) is initialized with all of the information that 
the terminfo(4) boolean, numeric, and string variables 
refer to. The pointer may be saved before calling setup- 
term () again. Further calls to setuptermQ will allocate 
new space rather than reuse the space pointed to by 
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cur_term. 

setcurterm (nterm) 

Nterm is of type TERMINAL *. Set_curterm() sets the 
variable cur_term to nterm, and makes all of the ter- 
minfo(4) boolean, numeric and string variables use the 
values from nterm. 

delcurterm (oterm) 

Oterm is of type TERMINAL *. Del_curterm() frees the 
space pointed to by oterm and makes it available for 
further use. If oterm is the same as cur_term, then refer- 
ences to any of the terminfo(4) boolean, numeric, and 
string variables thereafter may refer to invalid memory 
locations until another setupterm() has been called. 

restartterm(term, fildes, errret) 

Like setuptermQ after a memory restore. 

char *tparm(str, p v p 2 p g ) 

Instantiate the string str with parms pj. A pointer is 
returned to the result of str with the. parameters applied. 

tputs(str, count, putc) 

Apply padding to the string str and output it. str must be 
a terminfo{4) string variable or the return value from 
tparm(), tgetstrQ, tigetstr() or tgotoQ. Count is the 
number of lines affected, or 1 if not applicable. Putc() is 
a putchar- like routine to which the characters are passed, 
one at a time. 

putp(str) 

A routine that calls tputs [str, 1, putcharQ]. 

vidputs(attrs, putc) 

Output a string that puts the terminal in the video attri- 
bute mode attrs, which is any combination of the attri- 
butes listed below. The characters are passed to the 
pi/fc/?ar-like routine putc(). 

vidattr (attrs) 

Like vidputsQ, except that it outputs through putchar. 

mvcur(oldrow, oldcol, newrow, newcol) 
Low-level cursor motion. 
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The following routines return the value of the capability 
corresponding to the terminfo(4) capname passed to them, 
such as xenl. 

tigetf lag (capname) 

The value -1 is returned if capname is not a boolean capa- 
bility. 

tigetnum (capname) 

The value -2 is returned if capname is not a numeric capa- 
bility. 

tigetstr (capname) 

The value (char *) -1 is returned if capname is not a string 
capability. 

char *boolnames[], *boolcodes[], *boolfnames[] 
char *numnames[], *numcodes[], *numf names [] 
char *strnames[], *strcodes[], *strfnames[] 

These null- terminated arrays contain the capnames, the 
termcap codes, and the full C names, for each of the ter- 
minfo{4) variables. 

Termcap Emulation 

These routines are included as a conversion aid for programs 
that use the termcap library. Their parameters are the same 
and the routines are emulated using the terminfo (4) database. 

tgetent(bp, name) 

Look up termcap entry for name. The emulation ignores 
the buffer pointer bp. 

tgetf lag (codename) 

Get the boolean entry for codename. 

tgetnum (codes) 

Get numeric entry for codename. 

char *tgetstr(codename, area) 

Return the string entry for codename. If area is not 
NULL, then also store it in the buffer pointed to by area 
and advance area. TputsQ should be used to output the 
returned string. 

char *tgoto(cap, col, row) 

Instantiate the parameters into the given capability. The 
output from this routine is to be passed to tputs(). 
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tputs(str, affcnt, putc) 

See tputs() above, under "Terminfo- Level Manipulations." 
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Miscellaneous 
traceoffQ 
traceon() 

Turn off and on debugging trace output when using the 
debug version of the curses library, /usr/lib/libdcurses.a. 
This facility is available only to customers with a source 
license. 

unctrl(c) 

This macro expands to a character string which is a print- 
able representation of the character c. Control characters 
are displayed in the "X notation. Printing characters are 
displayed as is. 

Unctrl() is a macro, defined in <unctrl.h>, which is 
automatically included by < curses.h > . 

char *keyname(c) 

A character string corresponding to the key c is returned. 

filter() 

This routine is one of the few that is to be called before 
initscrQ or newterm() is called. It arranges things so 
that curses thinks that there is a 1-line screen. Curses 
will not use any terminal capabilities that assume that they 
know what line on the screen the cursor is on. 

Use of cursor 

The special window curscr can be used in only a few routines. 
If the window argument to clearok() is curscr, the next call to 
wrefresh() with any window will cause the screen to be 
cleared and repainted from scratch. If the window argument 
to wrefresh() is curscr, the screen is immediately cleared and 
repainted from scratch. (This is how most programs would 
implement a "repaint-screen" routine.) The source window 
argument to overlayQ, overwrite(), and copywinQ may be 
curscr, in which case the current contents of the virtual termi- 
nal screen will be accessed. 

Obsolete Calls 

Various routines are provided to maintain compatibility in pro- 
grams written for older versions of the curses library. These 
routines are all emulated as indicated below. 

crmodeQ Replaced by cbreakQ. 
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fixtermQ Replaced by reset_prog_mode(). 
gettmode() A no-op. 
nocrmode() Replaced by nocbreak(). 
resetterm() Replaced by reset_shell_mode(). 
saveterm() Replaced by def_prog_mode(). 
setterm() Replaced by setupterm(). 
ATTRIBUTES 

The following video attributes, defined in <curses.h>, can be 
passed to the routines attron(), attroff(), and attrset(), or 
OR'ed with the characters passed to addch(). 



A 


STANDOUT 


Terminal's best highlighting mode 


A 


UNDERLINE 


Underlining 


A 


"reverse 


Reverse video 


a" 


BLINK 


Blinking 


A 


DIM 


Half bright 


A 


"bold 


Extra bright or bold 


a] 


ALTCHARSET 


Alternate character set 


A_ 


CHARTEXT 


Bit-mask to extract character 






[described under winch ()] 


A_ 


ATTRIBUTES 


Bit-mask to extract attributes 






[described under winch()] 


A 


NORMAL 


Bit mask to reset all attributes off 



(for example: attrset (A NORMAL) 

FUNCTION-KEYS 

The following function keys, defined in <curses.h>, might be 
returned by getchQ if keypad () has been enabled. Note that 
not all of these may be supported on a particular terminal if 
the terminal does not transmit a unique code when the key is 
pressed or the definition for the key is not present in the ter- 
minfo{A) database. 
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Name 


Value 


KEY BREAK 


0401 


KEY DOWN 


0402 


KEY UP 


0403 


KEY LEFT 


0404 


KEY RIGHT 


0405 


KEY HOME 


0406 


KEY BACKSPACE 


0407 


KEY~FO 


0410 


KEY F(n) 


(KEY F0 + 


KEY~DL 


0510 


KEY~IL 


0511 


KEY DC 


0512 


KEY IC 


0513 


KEY BC 


0514 


KEY CLEAR 


0515 


KEY EOS 


0516 


KEY EOL 


0517 


KEY SF 


0520 


KEY SR 


0521 


KEY NPAGE 


0522 


KEY PPAGE 


0523 


KEY STAB 


0524 


KEY CTAB 


0525 


KEY CATAB 


0526 


KEY ENTER 


0527 


KEY SRESET 


0530 


KEY RESET 


0531 


KEY PRINT 


0532 


KEY LL 


0533 


KEY A1 


0534 


KEY A3 


0535 


KEY B2 


0536 


KEY C1 


0537 


KEY C3 


0540 


KEY BTAB 


0541 


KEY BEG 


0542 


KEY CANCEL 


0543 


KEY CLOSE 


0544 
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Key name 

Break key (unreliable) 
The four arrow keys ... 



Home key (upward + left 
arrow) 

Backspace (unreliable) 
Function keys. Space for 
64 keys is reserved, 
(n)) Formula for f . 
Delete line 
Insert line 
Delete character 
Insert char or enter insert 
mode 

Exit insert char mode 
Clear screen 
Clear to end of screen 
Clear to end of line 
Scroll 1 line forward 
Scroll 1 line backwards 
(reverse) 
Next page 
Previous page 
Set tab 
Clear tab 
Clear all tabs 
Enter or send 
Soft (partial) reset 
Reset or hard reset 
Print or copy 

Home down or bottom (lower 

left). Keypad is arranged 

like this: 

A1 up A3 
left B2 right 
C1 down C3 

Upper left of keypad 

Upper right of keypad 

Center of keypad 

Lower left of keypad 

Lower right of keypad 

Back tab key 

Beg(inning) key 

Cancel key 

Close key 
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KEYCOMMAND 0545 

KEY_COPY 0546 

KEYCREATE 0547 

KEY_END 0550 

KEYEXIT 0551 

KEY_FIND 0552 

KEY_HELP 0553 

KEY_MARK 0554 

KEYMESSAGE 0555 

KEYMOVE 0556 

KEYNEXT 0557 

KEY_OPEN 0560 

KEY_OPTIONS 0561 

KEY_PREVIOUS 0562 

KEY_REDO 0563 

KEY_REFERENCE 0564 

KEY_REFRESH 0565 

KEYREPLACE 0566 

KEY_RESTART 0567 

KEY_RESUME 0570 

KEYSAVE 0571 

KEY_SBEG 0572 

KEY_SCANCEL 0573 

KEY_SCOMMAND 0574 

KEY_SCOPY 0575 

KEYSCREATE 0576 

KEYSDC 0577 

KEY_SDL 0600 

KEY_SELECT 0601 

KEY SEND 0602 

KEY~SEOL 0603 

KEY_SEXIT 0604 

KEY_SFIND 0605 

KEY_SHELP 0606 

KEY_SHOME 0607 

KEY_SIC 0610 

KEYSLEFT 0611 

KEY_SMESSAGE 0612 

KEY_SMOVE 0613 

KEYSNEXT 0614 

KEY_SOPTIONS 0615 

KEYSPREVIOUS 0616 

KEY_SPRINT 0617 

KEYSREDO 0620 

KEYSREPLACE 0621 

KEYSRIGHT 0622 

KEYSRSUME 0623 

KEYSSAVE 0624 

KEY_SSUSPEND 0625 



Cmd (command) key 
Copy key 
Create key 
End key 
Exit key 
Find key 
Help key 
Mark key 
Message key 
Move key 
Next object key 
Open key 
Options key 
Previous object key 
Redo key 
Ref(erence) key 
Refresh key 
Replace key 
Restart key 
Resume key 
Save key 

Shifted beginning key 
Shifted cancel key 
Shifted command key 
Shifted copy key 
Shifted create key 
Shifted delete char key 
Shifted delete line key 
Select key 
Shifted end key 
Shifted clear line key 
Shifted exit key 
Shifted find key 
Shifted help key 
Shifted home key 
Shifted input key 
Shifted left arrow key 
Shifted message key 
Shifted move key 
Shifted next key 
Shifted options key 
Shifted prev key 
Shifted print key 
Shifted redo key 
Shifted replace key 
Shifted right arrow 
Shifted resume key 
Shifted save key 
Shifted suspend key 
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KEY_SUNDO 
KEY_SUSPEND 
KEY UNDO 



0626 
0627 
0630 



Shifted undo key 
Suspend key 
Undo key 



LINE GRAPHICS 

The following variables may be used to add line-drawing char- 
acters to the screen with waddch(). When defined for the ter- 
minal, the variable will have the AALTCHARSET bit turned 
on. Otherwise, the default charcter listed below will be stored 
in the variable. The names were chosen to be consistent with 
the DEC VT100 nomenclature. 



Name 


Default 


Glyph Description 


ACS ULCORNER 




upper left corner 


ACS~LLCORNER 




lower left corner 


ACS~URCORNER 


+ 


upper right corner 


ACS~LRCORNER 


+ 


lower right corner 


ACS RTEE 


+ 


riaht tee ( -1 ) 


ACS LTEE 


+ 


left tee (|- ) 


ACS BTEE 


+ 


bottom tee ([_) 


ACS TTEE 


+ 


too tee (1 ) 


ACS HLINE 




horizontal line 


ACS VLINE 


i 
i 


vertical line 


ACS PLUS 


+ 


plus 


ACS S1 




scan line 1 


ACS S9 




scan line 9 


ACS DIAMOND 


+ 


diamond 


ACS CKBOARD 




checker board (stipple) 


ACS DEGREE 




degree symbol 


ACS PLMINUS 


# 


plus/minus 


ACS BULLET 


0 


bullet 


ACS LARROW 


< 


arrow pointing left 


ACS RARROW 


> 


arrow pointing right 


ACS DARROW 


V 


arrow pointing down 


ACS UARROW 




arrow pointing up 


ACS BOARD 


# 


board of squares 


ACS LANTERN 


# 


lantern symbol 


ACS BLOCK 


# 


solid square block 



RETURN VALUES 

All routines return the integer OK upon successful completion 
and the integer ERR upon failure, unless otherwise noted in 
the preceding routine descriptions. 
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All macros return the value of their w version, except 
setscrreg(), wsetscrregQ, getsyx(), getyxQ, getbegyQ, get- 
maxyx(). For these macros, no useful value is returned. 

Routines that return pointers always return (type *) NULL on 
error. 

BUGS 

Currently typeahead checking is done using a nodelay read 
followed by an ungetchQ of any character that may have 
been read. Typeahead checking is done only if wgetchQ has 
been called at least once. This will be changed when proper 
kernel support is available. Programs which use a mixture of 
their own input routines with curses input routines may wish 
to call typeahead(-l) to turn off typeahead checking. 

The argument to napms() is currently rounded up to the 
nearest second. 

Draino(ms) only works for ms equal to 0. 
WARNINGS 

To use the new curses features, use the version of curses. 
All programs that ran with UNIX System V Release 2 curses 
will run with System V Release 3.0. You may link applications 
with object files based on the Release 2 curses /terminfo with 
the Release 3.0 libcurses.a library. You may link applications 
with object files based on the Release 3.0 curses /terminfo with 
the Release 2 libcurses.a library, so long as the application 
does not use the new features in the Release 3.0 
curses /terminfo . 

The plotting library p/of(3X) and the curses library curses (3X) 
both use the names erase () and move(). The curses versions 
are macros. If you need both libraries, put the p/of(3X) code 
in a different source file than the curses (3X) code, and/or 
#undef moveQ and erase() in the plot(3X) code. 

Between the time a call to initscrQ and endwinQ has been 
issued, use only the routines in the curses library to generate 
output. Using system calls or the "standard I/O package" 
[see sfc//o(3S)] for output during that time can cause 
unpredictable results. 

SEE ALSO 

cc(1), ld(1), ioctl(2), plot(3X), putc(3S), scanf(3S), stdio(3S), 
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system(3S), vprintf(3S), profile(4), term(4), terminfo(4), 
varargs(5). 

termio(7), tty(7) in the Administrator's Reference Manual. 
"curses/terminfo" in the Programmer's Guide. 
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NAME 

libdev - manipulate Volume Home Blocks (VHB) 

SYNOPSIS 

#include < sys/gdisk.h > 

struct vhbd *vhbd; 
short si, *slp; 
char *s, *device; 
int fd; 

int gdnsec(vhbd, si) 
int gdstrk(vhbd, si) 
int gdftrk(vhbd, si) 
int gdnszc(vhbd) 
int isdisk(fd) 

struct vhbd *readvhb(s, sip) 

struct vhbd *sreadvhb(device) 

struct vhbd *freadvhb(fd, sip) 

char *adevname(fd) 

char *bdevname(s) 

int dismnt(fd) 

char *gdname(s, sip) 

char *fgdname(fd, sip) 

int gdnlblk(fd) 

int writvhb(s, si, vhbd) 

int swritevhb(device, vhbd) 

int fwritevhb(fd, si, vhbd) 

DESCRIPTION 

In each of the above subroutines the arguments denote: 

vhbd A pointer to a disk volume home block, as returned 
by readvhb, sreadvhb, or freadvhb. 

si Slice number on the drive. 

sip Pointer to a slice number. This argument is actually 

used by the subroutine to return a slice number. 

s The name of a special file in /dev/rdsk. This 

filename is used to obtain a file descriptor to 
access a VHB. The name need not be for slice 
zero of the disk. 

device The name of a special file in /dev/rdsk. This 
filename is used to obtain a file descriptor to 
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access a VHB. 
a disk. 



The name must be for slice zero of 



fd Open file descriptor for slice zero of a disk. 

The subroutines in /usr/lib/libdev.a form a device and 
machine independent interface to the VHB of 6000/50 disks. 
The function of each subroutine is described below. 

Gdnsec Returns the number of sectors in slice si of the 
VHB indicated by vhbd. 

Gdstrk Returns the starting track of slice si of the VHB 
pointed to by vhbd. 

Gdftrk returns 1 if slice si of the VHB pointed to by vhbd 
extends to the end of the disk. 

Gdnszc Returns the number of sectors per cylinder. 

Isdlsk Returns 1 if the file descriptor fd is opened to a 
special disk device. 

Readvhb, Sreadvhb, and Freadvhb 

Return a pointer to a VHB for the device described 
by their arguments. 

Adevname 

Returns the character device name for the disk 
drive that the file descriptor fd is opened to. 

Bdevname 

Returns the block device name for the disk drive 
that the string s names. The filename S may be 
either for any slice on either a raw or a block dev- 
ice. 

Dismnt Exercises the GDDISMNT ioctl call for the disk drive 
that the file descriptor fd is opened to. 

Gdname Returns the file name for the character special slice 
zero of a disk that the filename s name a slice of. 
The value pointed to by sip is set to the slice 
number of the filename s. Fgdname performs as 
does gdname, but uses the file descriptor fd 
instead of the filename s. 

Gdnlblk Returns the number of logical blocks in the slice 
that the file descriptor fd is opened to. 
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writevhb, swritevhb, and fwritevhb 

Write the volume home block onto the device. 

FILES 

/dev/rdsk/c?d?s? 

/dev/dsk/c?d?s? 

/usr/lib/libdev.a 

SEE ALSO 

iv(1) in the User's Reference Manual. 

disk(7) in the Administrator's Reference Manual. 
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NAME 



ocurse - optimized screen functions 

SYNOPSIS 

#include < ocurse. h> 

DESCRIPTION 

Ocurse is the old Berkeley curses library that uses 
otermcap{4). 

These functions optimally update the screen. 

Each curses program begins by calling initscr and ends by 
calling endwin. 

Before a program can change a screen, it must specify the 
changes. It stores changes in a variable of type WINDOW by 
calling curses functions with the variable as argument. Once 
the variable contains all the changes desired, the program 
calls wrefresh to write the changes to the screen. 

Most programs only need a single WINDOW variable. Curses 
provides a standard WINDOW variable for this case and a 
group of functions that operate on it. The variable is called 
stdscr; its special functions have the same name as the gen- 
eral functions minus the initial w. 



FILES 



/usr/include/ocurse.h 



header file 



/usr/lib/libocurse.a 



/usr/lib/libtermcap.a 



curses library 

termcap library, used by curses 



SEE ALSO 

otermcap(4). 



FUNCTIONS 

addch(ch) 

addstr(str) 

box(win,vert,hor) 

crmode() 

clearQ 

clearok(scr.boolf) 
clrtobot() 
clrtoeol() 
delch() 



Add a character to stdscr. 
Add a string to stdscr. 
Draw a box around a window. 
Set cbreak mode. 
Clear stdscr. 
Set clear flag for scr. 
Clear to bottom on stdscr. 
Clear to end of line on stdscr. 
Delete a character. 
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deleteln() 
delwin(win) 
echo() 
endwin() 
erase () 
getch() 
getcap(name) 
getstr(str) 
gettmode() 
getyx(win,y,x) 
inch() 

initscr() 
insch(c) 
insertln() 

leaveok(win,boolf) 



Delete a line. 
Delete win. 
Set echo mode. 
End window modes. 
Erase stdscr. 

Get a character through stdscr. 
Get terminal capability name. 
Get a string through stdscr. 
Get tty modes. 
Get (y,x) co-ordinates. 
Get character at current (y,x) co- 
ordinates. 
Initialize screens. 
Insert a char. 
Insert a line. 
Set leave flag for win. 
longname(termbuf,name) Get long name from termbuf. 
move(y.x) Move to (y,x) on stdscr. 

mvcurflasty.lastx.newy.newx) 

Actually move cursor. 
newwin(lines,cols l begin_y,begin_x) 

Create a new window. 
Set newline mapping. 
Unset cbreak mode. 
Unset echo mode. 
Unset newline mapping. 
Unset raw mode. 
Overlay win1 on win2. 
Overwrite win1 on top of win2. 
.) Printf on stdscr. 
Set raw mode. 

Make current screen look like 
stdscr. 

Reset tty flags to stored value. 
Stored current tty flags. 
.) Scant through stdscr. 
Scroll win one line. 
Set scroll flag. 

Set term variables for name. 
End standout mode. 



nl() 

nocrmode() 
noecho() 
nonl() 
norawQ 

overlay(win1,win2) 
overwrite(win1 ,win2) 
printw(fmt,arg1 ,arg2,. 
raw() 
refresh () 



resetty() 
savetty() 

scanw(fmt,arg1 ,arg2, . 
scroll (win) 
scrollok(win,boolf) 
setterm(name) 
standend() 
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standout () 
subwin(win,lines,cols, 

touchwin(win) 

unctrl(ch) 

waddch(win,ch) 

waddstr(win,str) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win,c) 

wdeleteln(win) 

werase(win) 

wgetchjwin) 

wgetstr(win,str) 

winch (win) 

winsch(win,c) 

winsertln(win) 

wmove(win,y,x) 

wprintw(win,fmt,arg1 

wrefresh(win) 
wscanw(win,fmt,arg1 

wstandend(win) 
wstandout(win) 



Start standout mode. 
begin_y,begin_x) 

Create a subwindow. 
"change" all of win. 
Printable version of ch. 
Add char to win. 
Add string to win. 
Clear win . 

Clear to bottom of win. 
Clear to end of line on win. 
Delete character from win. 
Delete line from win. 
Erase win. 

Get a character through win. 

Get a string through win. 

Get character at current (y,x) in win. 

Insert character into win. 

Insert line into win. 

Set current (y,x) co-ordinates on 

win. 
,arg2, . . .) 

Printf on win. 

Make screen look like win . 
,arg2, . . .) 

Scanf through win. 

End standout mode on win. 

Start standout mode on win. 
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NAME 

tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs - terminal 
independent operations 

SYNOPSIS 
char PC; 
char *BC; 
char *UP; 
short ospeed; 

tgetent(bp, name) 
char *bp, *name; 

tgetnum(id) 
char *id; 

tgetflag(id) 
char *id; 

char * 

tgetstr(id, area) 
char *id, **area; 

char * 

tgoto(cmstr, destcol, destline) 
char *cmstr; 

tputs(cp, affcnt, outc) 
register char *cp; 
int affcnt; 
int (*outc)(); 

DESCRIPTION 

These functions are now emulated in curses (3X) using the fer- 
minfo(4) databases. Refer to the "Termcap Emulation" sec- 
tion in curses (3X). 

This manual page is included for historical reason only. New 
and existing applications should use curses (3X) and ter- 
minfo{4) for terminal independent operations. However, as a 
conversion aid, these functions extract and use information 
from terminal descriptions that follow the conventions in 
otermcap(4). The functions only do basic screen manipula- 
tion: they find and output specified terminal function strings 
and interpret the cm string. 
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Tgetent finds and copies a terminal description. Name is the 
name of the description; bp points to a buffer to hold the 
description. Tgetent passes bp to the other termcap func- 
tions; the buffer must remain allocated until the program is 
done with the termcap functions. 

Tgetent uses the TERM and TERMCAP environment variables 
to locate the terminal description. 

• If TERMCAP isn't set or is empty, tgetent searches for 
name in /etc/termcap. 

• If TERMCAP contains the full pathname of a file (any 
string that begins with /), tgetent searches for name in 
that file. 

• If TERMCAP contains any string that does not begin with 
/ and TERM is not set or matches name, tgetent copies 
the TERMCAP string. 

• If TERMCAP contains any string that does not begin with 
/ and TERM does not match name, tgetent searches for 
name in /etc/termcap. 

Tgetent returns -1 if it couldn't open the terminal capability 
file, 0 if it couldn't find an entry for name, and 1 upon success. 

Tgetnum returns the value of the numeric capability whose 
name is id. It returns -1 if the terminal lacks the specified 
capability or it is not a numeric capability. 

Tgetflag returns 1 if the terminal has boolean capability whose 
name is id, 0 if it does not or it is not a boolean capability. 

Tgetstr copies and interprets the value of the string capability 
named by id. Tgetstr expands instances in the string of \ and 
\ It leaves the expanded string in the buffer indirectly 
pointed to by area and leaves the buffer's direct pointer point- 
ing to the end of the expanded string; for example, 

tgetstr("cl", &ptr); 

where ptr is a character pointer, not an array name. Tgetstr 
returns a (direct) pointer to the beginning of the string. 

Tgoto interprets the % escapes in a cm string. It returns 
cmstr with the % sequences changed to the position indicated 
by destcol and destline. This function must have the external 
variables BC and UP set to the values of the be and up 
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capabilities; if the terminal lacks the capability, set the external 
variable to null. If tgoto can't interpret all the % sequences in 
cm, it returns "OOPS" 

Tgoto avoids producing characters that might be misinter- 
preted by the terminal interface. If expanding a % sequence 
would produce a control-d or null, the function will, if possible, 
send the cursor to the next line or column and use BC or UP 
to move to the correct location. Note that tgoto does not 
avoid producing tabs; a program must turn off the TAB3 
feature of the terminal interface [termio(7)]. This is a good 
idea anyway: some terminals use the tab character as a non- 
destructive space. 

Tputs directs the output of a string returned by tgetstr or 
tgoto. This function must have the external variable PC set to 
the value of the pc capability; if the terminal lacks the capabil- 
ity, set the external variable to null. Tputs interprets any delay 
at the beginning of the string. Cp is the string to be output; 
affcnt is the number of lines affected by the action (1 if 
"number of lines affected" doesn't mean anything); and outc 
points to a function that takes a single char argument and 
outputs it, such as putchar. 

FILES 

/usr/lib/libtermcap.a library 
/etc/termcap data base 

SEE ALSO 

curses(3X), terminfo(4). 
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NAME 

sputl, sgetl - access long integer data in a machine- 
independent fashion 

SYNOPSIS 

void sputl (value, buffer) 
long value; 
char *buffer; 

long sgetl (buffer) 
char *buffer; 

DESCRIPTION 

Sputl takes the four bytes of the long integer value and places 
them in memory starting at the address pointed to by buffer. 
The ordering of the bytes is the same across all machines. 

Sgetl retrieves the four bytes in memory starting at the 
address pointed to by buffer and returns the long integer 
value in the byte ordering of the host machine. 

The combination of sputl and sgetl provides a machine- 
independent way of storing long numeric data in a file in 
binary form without conversion to characters. 

A program which uses these functions must be loaded with 
the object-file access routine library /lib/libld.a. 
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